Contents | Prev | Next | Index

CHAPTER 18

Documentation Comments


Java programs can include documentation in their source code, in special documentation comments (§3.7). Such comments can appear before each class or interface declaration and before each method, constructor, or field declaration. Hypertext web pages can then be produced automatically from the source code of the program and these documentation comments.

This chapter gives an informal description of documentation comments. A complete formal specification would require a detailed description of those parts of the Hypertext Markup Language (HTML) that can be used within the documentation comments, which is beyond the scope of this specification.

18.1 The Text of a Documentation Comment

The text of a documentation comment consists of the characters between the /** that begins the comment and the */ that ends it. The text is divided into one or more lines. On each of these lines, leading * characters are ignored; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded.

So, for example, in the comment:


/**XYZ
  ** Initialize to pre-trial defaults.
  123*/
the text of the comment has three lines. The first line consists of the text "XYZ"; the second line consists of the text " Initialize to pre-trial defaults." and the third line consists of the text "123"

18.2 HTML in a Documentation Comment

Text in a documentation comment may use HTML markers for formatting, with the exception that the specific markers <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, and <HR> are reserved for use by the documentation generator and should not be used in the text. A complete description of HTML is available from the web site http://www.w3.org and also through the Internet documentation database at http://www.internic.net, where the document "Hypertext Markup Language -Version 2.0" by T. Berners-Lee and D. Connolly may be found as RFC1866.

18.3 Summary Sentence and General Description

The first sentence of each documentation comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tagline (as defined below). This simple rule means that a first sentence such as:

This is a simulation of Prof. Knuth's MIX computer.
will not work properly, because the period after the abbreviation "Prof" ends the first sentence, as far as the Java documentation comment processor is concerned. Take care to avoid such difficulties.

Sentences following the summary sentence but preceding the first tagged paragraph (if any) form the general description part of the documentation comment.

18.4 Tagged Paragraphs

A line of a documentation comment that begins with the character @ followed by one of a few special keywords starts a tagged paragraph. The tagged paragraph also includes any following lines up to, but not including, either the first line of the next tagged paragraph or the end of the documentation comment.

Tagged paragraphs identify certain information that has a routine structure, such as the intended purpose of each parameter of a method, in a form that the documentation comment processor can easily marshal into standard typographical formats for purposes of presentation and cross-reference.

Different kinds of tagged paragraphs are available for class and interface declarations and for method, field, and constructor declarations.

18.4.1 The @see Tag

The following are examples of @see paragraphs, which may be used in any documentation comment to indicate a cross-reference to a class, interface, method, constructor, field, or URL:


@see java.lang.String
@see String
@see java.io.InputStream;
@see String#equals
@see java.lang.Object#wait(int)
@see java.io.RandomAccessFile#RandomAccessFile(File, String)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>
The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name.

A documentation comment may contain more than one @see tag.

18.4.2 The @author Tag

The following are examples of @author taglines, which may be used in documentation comments for class and interface declarations:


@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker
The information in an @author paragraph has no special internal structure.

A documentation comment may contain more than one @author tag. Alternatively, a single @author paragraph may mention several authors:


@author Jack Kent, Peggy Parish, Crockett Johnson,
	James Marshall, Marjorie Weinman Sharmat,
	Robert McCloskey, and Madeleine L'Engle
However, we recommend specifying one author per @author paragraph, which allows the documentation processing tool to provide the correct punctuation in all circumstances.

18.4.3 The @version Tag

The following is an example of a @version paragraph, which may be used in documentation comments for class and interface declarations:

@version 493.0.1beta
The information in a @version paragraph has no special internal structure.

A documentation comment may contain at most one @version tag.

18.4.4 The @param Tag

The following are examples of @param paragraphs, which may be used in documentation comments for method and constructor declarations:


@param file the file to be searched
@param pattern
	the pattern to be matched during the search
@param count      the number of lines to print for each match
The information in a @param paragraph should consist of the name of the parameter followed by a short description.

A documentation comment may contain more than one @param tag. The usual convention is that if any @param paragraphs are present in a documentation comment, then there should be one @param paragraph for each parameter of the method or constructor, and the @param paragraphs should appear in the order in which the parameters are declared.

18.4.5 The @return Tag

The following is an example of a @return paragraph, which may be used in documentation comments for declarations of methods whose result type is not void:

@return the number of widgets that pass the quality test
The information in a @return paragraph has no special internal structure. The usual convention is that it consists of a short description of the returned value.

A documentation comment may contain at most one @return tag.

18.4.6 The @exception Tag

The following is an example of an @exception paragraph, which may be used in documentation comments for method and constructor declarations:


@exception IndexOutOfBoundsException
				the matrix is too large
@exception UnflangedWidgetException the widget does not
				have a flange, or its flange has size zero
@exception java.io.FileNotFoundException the file
				does not exist
The information in an @exception paragraph should consist of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown.

A documentation comment may contain more than one @exception tag.

18.5 Example

Here, as an example, is a version of the source code for the class Object of the package java.lang, including its documentation comments.


/*
 * @(#)Object.java 1.37 96/06/26
 *
 * Copyright (c) 1994, 1995, 1996 Sun Microsystems, Inc.
 * All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this
 * software and its documentation for NON-COMMERCIAL purposes
 * and without fee is hereby granted provided that this
 * copyright notice appears in all copies. Please refer to
 * the file "copyright.html" for further important copyright
 * and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
 * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED,
 * INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
 * NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */


package java.lang;
/** * The root of the Class hierarchy. Every Class in the * system has Object as its ultimate parent. Every variable * and method defined here is available in every Object. * @see Class * @version 1.37, 26 Jun 1996 */
public class Object { /** * Returns the Class of this Object. Java has a runtime * representation for classes--a descriptor of type Class * --which the method getClass() returns for any Object. */ public final native Class getClass();
/** * Returns a hashcode for this Object. * Each Object in the Java system has a hashcode. * The hashcode is a number that is usually different * for different Objects. It is used when storing Objects * in hashtables. * Note: hashcodes can be negative as well as positive. * @see java.util.Hashtable */ public native int hashCode();
/** * Compares two Objects for equality. * Returns a boolean that indicates whether this Object * is equivalent to the specified Object. This method is * used when an Object is stored in a hashtable. * @param obj the Object to compare with * @return true if these Objects are equal; * false otherwise. * @see java.util.Hashtable */ public boolean equals(Object obj) { return (this == obj); }
/** * Creates a clone of the object. A new instance is * allocated and a bitwise clone of the current object * is placed in the new object. * @return a clone of this Object. * @exception OutOfMemoryError If there is not enough * memory. * @exception CloneNotSupportedException Object * explicitly does not want to be * cloned, or it does not support * the Cloneable interface. */ protected native Object clone() throws CloneNotSupportedException;


	/**
	 * Returns a String that represents this Object.
	 * It is recommended that all subclasses override
	 * this method.
	 */
	public String toString() {
		return getClass().getName() + "@" +
			Integer.toHexString(hashCode());
	}

/** * Notifies a single waiting thread on a change in * condition of another thread. The thread effecting * the change notifies the waiting thread using notify(). * Threads that want to wait for a condition to change * before proceeding can call wait(). <p> * <em>The method notify() can be called only by the * thread that is the owner of the current object's * monitor lock.</em> * * @exception IllegalMonitorStateException If the * current thread is not the owner * of the Object's monitor lock. * @see Object#wait * @see Object#notifyAll */ public final native void notify();
/** * Notifies all the threads waiting for a condition to * change. Threads that are waiting are generally waiting * for another thread to change some condition. Thus, the * thread effecting a change that more than one thread is * waiting for notifies all the waiting threads using * the method notifyAll(). Threads that want to wait for * a condition to change before proceeding can call * wait(). <p> * <em>The method notifyAll() can be called only by the * thread that is the owner of the current object's * monitor lock.</em> * * @exception IllegalMonitorStateException If the * current thread is not the owner * of the Object's monitor lock. * @see Object#wait * @see Object#notify */ public final native void notifyAll();

	/**
	 * Causes a thread to wait until it is notified or the
	 * specified timeout expires. <p>
	 * <em>The method wait(millis) can be called only by
	 * the thread that is the owner of the current object's
	 * monitor lock.</em>
	 *
	 * @param 				millis			the maximum time to wait,
	 * 								in milliseconds
	 * @exception					IllegalMonitorStateException If the
	 * 						current thread is not the owner
	 * 						of the Object's monitor lock.
	 * @exception 					InterruptedException Another thread has
	 * 						interrupted this thread. 
	 */
	public final native void wait(long millis)
		throws InterruptedException;

/** * More accurate wait. * <em>The method wait(millis, nanos) can be called only * by the thread that is the owner of the current * object's monitor lock.</em> * * @param millis the maximum time to wait, * in milliseconds * @param nano additional time to wait, * in nanoseconds * (range 0-999999) * @exception IllegalMonitorStateException If the * current thread is not the owner * of the Object's monitor lock. * @exception InterruptedException Another thread has * interrupted this thread. */ public final void wait(long millis, int nanos) throws InterruptedException { if (nanos >= 500000 || (nanos != 0 && millis==0)) timeout++; wait(timeout); }
/** * Causes a thread to wait forever until it is notified. * <p> * <em>The method wait() can be called only by the * thread that is the owner of the current object's * monitor lock.</em> *
	 * @exception					IllegalMonitorStateException If the
	 * 						current thread is not the owner
	 * 						of the Object's monitor lock.
	 * @exception 					InterruptedException Another thread has
	 * 						interrupted this thread. 
	 */
	public final void wait() throws InterruptedException {
		wait(0);
	}


	/**
	 * Code to perform when this object is garbage collected.
	 * The default is that nothing needs to be performed.
	 * 
	 * Any exception thrown by a finalize method causes the
	 * finalization to halt.  But otherwise, it is ignored.
	 */
	protected void finalize() throws Throwable { }

}
From this source code, the javadoc tool produced the following HTML file, which is available for browsing at http://java.sun.com/Series, our Java Series web site:

<!--NewPage-->

<html>

<head>

<!-- Generated by javadoc on Wed Jun 26 11:40:38 EDT 1996 -->

<a name="_top_"></a>

<title>

Class java.lang.Object

</title>

</head>

<body>

<pre>

<a href="packages.html">All Packages</a> <a href="tree.html">Class Hierarchy¬
</a> <a href="Package-java.lang.html">This Package</a> <a href="java.lang.N¬
umber.html#_top_">Previous</a> <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a> <a href="AllNames.html">Index</a></pre>

<hr>

<h1>

Class java.lang.Object

</h1>

<pre>

java.lang.Object

</pre>

<hr>

<dl>

<dt> public class <b>Object</b>

</dl>

The root of the Class hierarchy. Every Class in the

system has Object as its ultimate parent. Every variable

and method defined here is available in every Object.

<dl>

<dt> <b>Version:</b>

<dd> 1.37, 26 Jun 1996

<dt> <b>See Also:</b>

<dd> <a href="java.lang.Class.html#_top_">Class</a>

</dl>

<hr>

<a name="index"></a>

<h2>

<img src="images/constructor-index.gif" width=275 height=38 alt="Constructo¬
r Index">

</h2>

<dl>

<dt> <img src="images/yellow-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#Object()"><b>Object</b></a>()

<dd>

</dl>

<h2>

<img src="images/method-index.gif" width=207 height=38 alt="Method Index">

</h2>

<dl>

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#clone()"><b>clone</b></a>()

<dd> Creates a clone of the object.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#equals(java.lang.Object)"><b>equals</b></a>(Object)

<dd> Compares two Objects for equality.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#finalize()"><b>finalize</b></a>()

<dd> Code to perform when this object is garbage collected.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#getClass()"><b>getClass</b></a>()

<dd> Returns the Class of this Object.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#hashCode()"><b>hashCode</b></a>()

<dd> Returns a hashcode for this Object.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#notify()"><b>notify</b></a>()

<dd> Notifies a single waiting thread on a change in

condition of another thread.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#notifyAll()"><b>notifyAll</b></a>()

<dd> Notifies all the threads waiting for a condition to

change.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#toString()"><b>toString</b></a>()

<dd> Returns a String that represents this Object.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#wait()"><b>wait</b></a>()

<dd> Causes a thread to wait forever until it is notified.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#wait(long)"><b>wait</b></a>(long)

<dd> Causes a thread to wait until it is notified or the

specified timeout expires.

<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">

<a href="#wait(long, int)"><b>wait</b></a>(long, int)

<dd> More accurate wait.

</dl>

<a name="constructors"></a>

<h2>

<img src="images/constructors.gif" width=231 height=38 alt="Constructors">

</h2>

<a name="Object"></a>

<a name="Object()"><img src="images/yellow-ball.gif" width=12 height=12 alt="¬
o "></a>

<b>Object</b>

<pre>

public Object()

</pre>

<a name="methods"></a>

<h2>

<img src="images/methods.gif" width=151 height=38 alt="Methods">

</h2>

<a name="getClass()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="getClass"><b>getClass</b></a>

<pre>

public final <a href="java.lang.Class.html#_top_">Class</a> getClass()

</pre>

<dl>

<dd> Returns the Class of this Object. Java has a runtime

representation for classes--a descriptor of type Class

--which the method getClass() returns for any Object.

</dl>

<a name="hashCode()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="hashCode"><b>hashCode</b></a>

<pre>

public int hashCode()

</pre>

<dl>

<dd> Returns a hashcode for this Object.

Each Object in the Java system has a hashcode.

The hashcode is a number that is usually different

for different Objects. It is used when storing Objects

in hashtables.

Note: hashcodes can be negative as well as positive.

<dl>

<dt> <b>See Also:</b>

<dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>

</dl>

</dl>

<a name="equals(java.lang.Object)"><img src="images/red-ball.gif" width=12 he¬
ight=12 alt=" o "></a>

<a name="equals"><b>equals</b></a>

<pre>

public boolean equals(<a href="#_top_">Object</a> obj)

</pre>

<dl>

<dd> Compares two Objects for equality.

Returns a boolean that indicates whether this Object

is equivalent to the specified Object. This method is

used when an Object is stored in a hashtable.

<dl>

<dt> <b>Parameters:</b>

<dd> obj - the Object to compare with

<dt> <b>Returns:</b>

<dd> true if these Objects are equal;

false otherwise.

<dt> <b>See Also:</b>

<dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>

</dl>

</dl>

<a name="clone()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "¬
></a>

<a name="clone"><b>clone</b></a>

<pre>

protected <a href="#_top_">Object</a> clone() throws <a href="java.lang.Clo¬
neNotSupportedException.html#_top_">CloneNotSupportedException</a>

</pre>

<dl>

<dd> Creates a clone of the object. A new instance is

allocated and a bitwise clone of the current object

is placed in the new object.

<dl>

<dt> <b>Returns:</b>

<dd> a clone of this Object.

<dt> <b>Throws:</b> <a href="java.lang.OutOfMemoryError.html#_top_">OutOf¬
MemoryError</a>

<dd> If there is not enough

memory.

<dt> <b>Throws:</b> <a href="java.lang.CloneNotSupportedException.html#_t¬
op_">CloneNotSupportedException</a>

<dd> Object

explicitly does not want to be

cloned, or it does not support

the Cloneable interface.

</dl>

</dl>

<a name="toString()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="toString"><b>toString</b></a>

<pre>

public <a href="java.lang.String.html#_top_">String</a> toString()

</pre>

<dl>

<dd> Returns a String that represents this Object.

It is recommended that all subclasses override

this method.

</dl>

<a name="notify()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ¬
"></a>

<a name="notify"><b>notify</b></a>

<pre>

public final void notify()

</pre>

<dl>

<dd> Notifies a single waiting thread on a change in

condition of another thread. The thread effecting

the change notifies the waiting thread using notify().

Threads that want to wait for a condition to change

before proceeding can call wait(). <p>

<em>The method notify() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

<dl>

<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

<dd> If the

current thread is not the owner

of the Object's monitor lock.

<dt> <b>See Also:</b>

<dd> <a href="#wait">wait</a>, <a href="#notifyAll">notifyAll</a>

</dl>

</dl>

<a name="notifyAll()"><img src="images/red-ball.gif" width=12 height=12 alt="¬
o "></a>

<a name="notifyAll"><b>notifyAll</b></a>

<pre>

public final void notifyAll()

</pre>

<dl>

<dd> Notifies all the threads waiting for a condition to

change. Threads that are waiting are generally waiting

for another thread to change some condition. Thus, the

thread effecting a change that more than one thread is

waiting for notifies all the waiting threads using

the method notifyAll(). Threads that want to wait for

a condition to change before proceeding can call

wait(). <p>

<em>The method notifyAll() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

<dl>

<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

<dd> If the

current thread is not the owner

of the Object's monitor lock.

<dt> <b>See Also:</b>

<dd> <a href="#wait">wait</a>, <a href="#notify">notify</a>

</dl>

</dl>

<a name="wait(long)"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="wait"><b>wait</b></a>

<pre>

public final void wait(long millis) throws <a href="java.lang.InterruptedEx¬
ception.html#_top_">InterruptedException</a>

</pre>

<dl>

<dd> Causes a thread to wait until it is notified or the

specified timeout expires. <p>

<em>The method wait(millis) can be called only by

the thread that is the owner of the current object's

monitor lock.</em>

<dl>

<dt> <b>Parameters:</b>

<dd> millis - the maximum time to wait,

in milliseconds

<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

<dd> If the

current thread is not the owner

of the Object's monitor lock.

<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

</dl>

<a name="wait(long, int)"><img src="images/red-ball.gif" width=12 height=12 a¬
lt=" o "></a>

<a name="wait"><b>wait</b></a>

<pre>

public final void wait(long millis,

int nanos) throws <a href="java.lang.InterruptedExce¬
ption.html#_top_">InterruptedException</a>

</pre>

<dl>

<dd> More accurate wait.

<em>The method wait(millis, nanos) can be called only

by the thread that is the owner of the current

object's monitor lock.</em>

<dl>

<dt> <b>Parameters:</b>

<dd> millis - the maximum time to wait,

in milliseconds

<dd> nano - additional time to wait,

in nanoseconds

(range 0-999999)

<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

<dd> If the

current thread is not the owner

of the Object's monitor lock.

<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

</dl>

<a name="wait()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ">¬
</a>

<a name="wait"><b>wait</b></a>

<pre>

public final void wait() throws <a href="java.lang.InterruptedException.htm¬
l#_top_">InterruptedException</a>

</pre>

<dl>

<dd> Causes a thread to wait forever until it is notified.

<p>

<em>The method wait() can be called only by the

thread that is the owner of the current object's

monitor lock.</em>

<dl>

<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>

<dd> If the

current thread is not the owner

of the Object's monitor lock.

<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

</dl>

<a name="finalize()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a>

<a name="finalize"><b>finalize</b></a>

<pre>

protected void finalize() throws <a href="java.lang.Throwable.html#_top_">T¬
hrowable</a>

</pre>

<dl>

<dd> Code to perform when this object is garbage collected.

The default is that nothing needs to be performed.

Any exception thrown by a finalize method causes the

finalization to halt. But otherwise, it is ignored.

</dl>

<hr>

<pre>

<a href="packages.html">All Packages</a> <a href="tree.html">Class Hierarchy¬
</a> <a href="Package-java.lang.html">This Package</a> <a href="java.lang.N¬
umber.html#_top_">Previous</a> <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a> <a href="AllNames.html">Index</a></pre>

</body>

</html>

Many of the lines in this HTML file are far too long to fit onto these pages. We have used the character "¬" at the end of a line to indicate that the following line of text on the page is part of the same line in the generated file.

This generated HTML file is meant only as an example, not as a specification of the behavior of the javadoc tool, which may be changed over time to improve the HTML presentation of the documentation information.


Contents | Prev | Next | Index

Java Language Specification (HTML generated by Suzette Pelouch on February 24, 1998)
Copyright © 1996 Sun Microsystems, Inc. All rights reserved
Please send any comments or corrections to [email protected]