Javaプログラムでは，特別な文書化用注釈(3.7)という形式で，ソースコードの中に解説文書を含めることができる。この注釈は，クラス宣言又はインタフェース宣言の前，及びメソッド宣言，コンストラクタ宣言又はフィールド宣言の前に記述できる。プログラムのソースコード及び文書化用注釈から，ハイパテキストウェブページを自動的に生成することが可能である。
18.では，文書化用注釈の非形式的な記述を示す。完全で形式的な規定には，文書化用注釈内で使用するハイパテキストマーク付け言語(Hypertext Markup Language，以下HTML)の詳細な説明が必要となるが，この規定の範囲を超える。
文書化用注釈のテキストは，注釈を開始する/** と注釈を終了する */ との間の文字によって構成される。テキストは，1行又は複数の行に分割される。各注釈行の先行する文字 * は無視される。最初の行以外の行では，行頭の文字 * に先行する空白及びタブも無視される。
/**XYZ ** Initialize to pre-trial defaults. 123*/
注釈テキストは3行である。最初の行はテキスト"XYZ"，2行目はテキスト"Initialize to pre-trial defaults."，及び3行目はテキスト"123"によって構成される。
文書化用注釈内のテキストには，フォーマット用HTMLマーカを使うことができる。ただし，特定マーカ<H1>，<H2>，<H3>，<H4>，<H5>，<H6>，及び <HR> は，文書生成器の使用のために確保されていて，テキストでは使用できない。HTMLの完全な記述は，ウェブサイトhttp://www.w3.org から入手できる。http://www.internic.net（日本では，http://www.nic.ad.jp/index-j.html）におけるインタネット文書データベース経由でも入手できる。ここで，T.Berners-Lee，D. Connolly共著の“Hypertext Markup Language -Version2.0”が，RFC1866 として見つけられる。
各文書化用注釈の最初の文は，注釈の対象に対する，簡潔だが完全な説明を含む要約文とすることが望ましい。要約文は，空白，タブ若しくは行末記号が続く最初のピリオド，又は最初のタグ行（定義は後述する）で終了する。この単純な規則では，次に示すとおりの文が最初の文の場合は，問題となる。
This is a simulation of Prof. Knuth's MIX computer.
Java文書化用注釈プロセサに関する限り，略語"Prof"の後ろのピリオドが，最初の文を終了する。 この困難を避けるように注意すること。
要約文に続き最初のタグ付き段落（存在する場合）に先行する文を文書化用注釈の本体とする。
文字@で始まり特別なキーワードの一つが続く文書化用注釈の行から，タグ付き段落（tagged paragraph）が開始する。タグ付き段落は，次のタグ付き段落の最初の行の前，又は文書化用注釈の最後（*/）の前までを一つの段落とする。
タグ付き段落は，メソッドの各パラメータの意図された目的など，一定の構造をもつ特定の情報を示すものとし，文書化用注釈プロセサが，表示用及び相互参照用の標準的な印刷形式に簡単に処理できる形式とする。
クラス宣言及びインタフェース宣言，並びに，メソッド宣言，フィールド宣言及びコンストラクタ宣言のために，各種のタグを使用できる。
クラス，インタフェース，メソッド，コンストラクタ，フィールド又はURLの相互参照を示すために文書化用注釈で使用できる @see段落の例を，次に示す。
@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>
文字 # は，クラスの名前と，クラスのフィールド，メソッド又はコンストラクタの名前とを分離する。メソッド又はコンストラクタの名前の後の実引数型に括弧付き並びを含むことで，複数のオーバロードされたメソッド又はコンストラクタから一つを選択できる。
クラス宣言及びインタフェース宣言に関する，文書化用注釈で使用できる @author タグ行の例を，次に示す。
@author Mary Wollstonecraft @author Hildegard von Bingen @author Dorothy Parker
文書化用注釈には，複数の @authorタグを含んでよい。別の方法として，一つの @author 段落に複数の著者を記述してもよい。
@author Jack Kent, Peggy Parish, Crockett Johnson,
James Marshall, Marjorie Weinman Sharmat,
Robert McCloskey, and Madeleine L'Engle
ただし，文書処理ツールがあらゆる状況で正しい句読法を実現するために，一つの@author 段落に著者一人だけを記述することが望ましい。
クラス宣言及びインタフェース宣言に関する，文書化用注釈で使用できる @version 段落の例を，次に示す。
@version 493.0.1beta
@version 段落内の情報は，特別な内部構造をもたない。
文書化用注釈は，多くとも一つの @versionタグを含む。
メソッド宣言及びコンストラクタ宣言に関する，文書化用注釈で使用できる @param 段落の例を，次に示す。
@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
@param 段落内の情報は，パラメータの名前及びそれに続く短い説明によって構成されるのが望ましい。
文書化用注釈は，複数の @paramタグを含んでよい。通常は，文書化用注釈に @param段落が存在するとき，メソッド又はコンストラクタの各パラメタに対して一つの@param段落が存在し，@param 段落はそのパラメタの宣言順とする。
返却値の型が voidでないメソッド宣言に関して，文書化用注釈で使用できる @return 段落の例を，次に示す。
@return the number of widgets that pass the quality test
@return段落内の情報は，特別な内部構造をもたない。通常は，これは，返却値の簡単な記述によって構成される。
メソッド宣言及びコンストラクタ宣言に関する，文書化用注釈で使用できる@exception 段落の例を，次に示す。
@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
@exception 段落内の情報は，例外クラスの名前（単純名又は限定名）及びそれに続く例外が投げられる状況の簡単な記述によって構成される。
文書化用注釈は，複数の @exceptionタグを含んでよい。
パッケージ java.lang のクラス Objectに対する文書化用注釈を含んだソースコードを，次に示す。
/* * @(#)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 { }
}
このソースコードから，javadoc ツールが次のHTMLファイルを生成する。このHTMLファイルはhttp://java.sun.com/docs/books/index.htmlで見ることができる。
<!--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>
このHTMLファイルの大半の行は，ページ幅よりも長い。生成されたファイル内で同じ行の一部がそのページの次の行に渡ることを示すために，行末に文字"¬"を付ける。
この生成されたHTMLファイルはあくまで参考用とし，javadoc ツールの動作規定とはしない。javadoc ツールは，文書情報のHTML表現を改良するために変更されることがある。