The Java language supports special "doc comments," which
begin with /** and end with */. These comments are
not actually treated specially by the compiler, but can be
extracted and automatically turned into HTML documentation
by the javadoc program.
Because the lines of a doc comment are embedded within a
Java comment, any leading spaces and asterisks (*)
are stripped from each comment line before processing. A
doc comment may contain HTML markup tags, such as <PRE> and
<TT> for code usage examples, but should not contain HTML
structural tags such as <H2> or <HR>. Doc comments should
immediately precede the declaration of the class, field, or
method that they are associated with. The first sentence of
a doc comment should be a summary sentence, suitable for
display on its own. The following sentences may document
the feature in more detail.
Following the initial summary sentence and any additional
documentation, a doc comment may use special tags, which all
begin with the @ character and allow javadoc
to provide additional formatting for the documentation. The
available tags are listed below. When you use a special
javadoc tag, it must be the first thing on its line
within the doc comment. The text that follows a tag may
span more than one line, and continues until the next
javadoc tag is encountered or until the comment ends.
If you use more than one tag of the same type, they should
be on subsequent lines. For example, a class with multiple
authors, or a method with multiple arguments would use
multiple @author or @param tags.
- @see classname
-
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified class. It may be used
before classes, methods, or fields.
- @see full-classname
-
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified class. It may be used
before classes, methods, or fields.
- @see full-classname#method-name
-
This tag adds a "See Also:" entry to the documentation that
contains a hyperlink to the specified method of the
specified class. It may be used before classes, methods, or
fields.
- @version text
-
This tag adds a "Version:" entry containing the
specified text to the documentation. May only be used
before a class definition.
javadoc ignores this
tag unless the -version command-line argument is
specified.
- @author text
-
This tag adds an "Author:" entry containing the
specified text to the documentation. May only be used
before a class definition. javadoc ignores this
tag unless the -author command-line argument is
specified.
- @param parameter-name description
-
This tag adds the specified parameter and its specified
description to the "Parameters:" section of the current
method. If the description is longer than one line, it may
be continued on the next. May only be used before a method
definition.
- @return description
-
Adds a "Returns:" section containing the specified
description to the documentation. May only be used before a
method definition.
- @exception full-classname description
-
Adds a "Throws:" entry to the documentation. The entry
contains the specified class name of the exception and the
description specified, which should explain the significance
of the exception. May only be used before a method definition.
- @deprecated explanation
-
As of Java 1.1, this tag specifies that the following
class, method, or field has been deprecated. javac
notes this information in the class file it produces and
issues a warning when a program uses the deprecated feature.
javadoc adds a "Deprecated" entry to the documentation
that includes the specified explanation.
- @since version
-
As of Java 1.1, this undocumented tag is used to
specify when the class, method, or field that follows it was
added to the API. It should be followed by a version number
or other version specification. The JDK 1.1 version of
javadoc appears to ignore this tag.