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:

<html>

<head>

<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 Object

</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> Version:

<dd> 1.37, 26 Jun 1996

<dt> See Also:

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

</dl>

<hr>

<h2>

</h2>

<dl>

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

<dd>

</dl>

<h2>

</h2>

<dl>

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

<dd> Creates a clone of the object.

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

<dd> Compares two Objects for equality.

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

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

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

<dd> Returns the Class of this Object.

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

<dd> Returns a hashcode for this Object.

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

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

condition of another thread.

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

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

change.

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

<dd> Returns a String that represents this Object.

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

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

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

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

specified timeout expires.

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

<dd> More accurate wait.

</dl>

<h2>

</h2>

Object

<pre>

public Object()

</pre>

<h2>

</h2>

<a name="getClass">getClass</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">hashCode</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> See Also:

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

</dl>

<a name="equals">equals</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> Parameters:

<dd> obj - the Object to compare with

<dt> Returns:

<dd> true if these Objects are equal;

false otherwise.

<dt> See Also:

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

</dl>

<a name="clone">clone</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> Returns:

<dd> a clone of this Object.

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

<dd> If there is not enough

memory.

<dt> Throws: <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>

<a name="toString">toString</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">notify</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().

The method notify() can be called only by the

thread that is the owner of the current object's

monitor lock.

<dl>

<dt> Throws: <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> See Also:

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

</dl>

<a name="notifyAll">notifyAll</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().

The method notifyAll() can be called only by the

thread that is the owner of the current object's

monitor lock.

<dl>

<dt> Throws: <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> See Also:

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

</dl>

<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.

The method wait(millis) can be called only by

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

monitor lock.

<dl>

<dt> Parameters:

<dd> millis - the maximum time to wait,

in milliseconds

<dt> Throws: <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> Throws: <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

<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.

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

by the thread that is the owner of the current

object's monitor lock.

<dl>

<dt> Parameters:

<dd> millis - the maximum time to wait,

in milliseconds

<dd> nano - additional time to wait,

in nanoseconds

(range 0-999999)

<dt> Throws: <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> Throws: <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

<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.

The method wait() can be called only by the

thread that is the owner of the current object's

monitor lock.

<dl>

<dt> Throws: <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> Throws: <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a>

<dd> Another thread has

interrupted this thread.

</dl>

<a name="finalize">finalize</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>

</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

Documentation Comments

18.1 The Text of a Documentation Comment

18.2 HTML in a Documentation Comment

18.3 Summary Sentence and General Description

18.4 Tagged Paragraphs

18.4.1 The @see Tag

18.4.2 The @author Tag

18.4.3 The @version Tag

18.4.4 The @param Tag

18.4.5 The @return Tag

18.4.6 The @exception Tag

18.5 Example

18.4.1 The `@see` Tag

18.4.2 The `@author` Tag

18.4.3 The `@version` Tag

18.4.4 The `@param` Tag

18.4.5 The `@return` Tag

18.4.6 The `@exception` Tag