If an API is
to be usable, it must be documented. Traditionally API documentation was
generated manually, and keeping it in sync with code was a chore. The Java
programming environment eases this task with the Javadoc
utility.
Javadoc generates API documentation automatically from source code with
specially formatted documentation comments, more
commonly known as doc comments.
To document your
API properly, you must precede every exported class, interface,
constructor, method, and field declaration with a doc comment. If a class is
serializable, you should also document its serialized form (Item 75). In the
absence of a doc comment, the best that Javadoc can do is to reproduce the
declaration as the sole documentation for the affected API element.
The doc comment
for a method should describe succinctly the contract between the method and its
client. With the exception of methods in classes designed for inheritance
(Item 17), the contract should say what the method
does rather than how it does its job. The doc comment
should enumerate all of the method’s preconditions, which are
the things that have to be true in order for a client to invoke it, and its postconditions, which are the things that will be true after the invocation has
completed successfully. Typically, preconditions are described implicitly by
the @throws tags for
unchecked exceptions; each unchecked exception corresponds to a precondition
violation. Also, preconditions can be specified along with the affected
parameters in their @param tags. Finally,
documentation comments should describe the thread
safety of
a class or method, as discussed in Item 70.
To describe a
method’s contract fully, the doc comment should have an @param tag for every parameter, an @return tag unless the method has a void return type,
and an @throws tag for every
exception thrown by the method, whether checked or unchecked (Item 62).
All of these
conventionsare illustrated by the following short doc comment:
/**
* Returns the element at the specified position in this
list.
*
* <p>This method is <i>not</i>
guaranteed to run in constant
* time. In some implementations it may run in time
proportional
* to the element position.
*
* @param index index of element to return; must be
* non-negative and less than the size of this list
* @return the element at the specified position in this
list
* @throws IndexOutOfBoundsException if the index is out
of range
* ({@code index < 0 || index >= this.size()})
*/
E get(int index);
Notice the use
of HTML tags in this doc comment (<p>
and
<i>). The Javadoc
utility translates doc comments into HTML, and arbitrary HTML elements in doc
comments end up in the resulting HTML document. Occasionally, programmers go so
far as to embed HTML tables in their doc comments, although this is rare.
Also notice
the use of the Javadoc {@code} tag around the
code fragment in the @throws clause. This
serves two purposes: it causes the code fragment to be rendered in code font, and it suppresses processing of HTML markup
and nested Javadoc tags in the code fragment. The latter property is what
allows us to use the less-than sign (<) in the code
fragment even though it’s an HTML metacharacter. Prior to release 1.5, code
fragments were included in doc comments by using HTML tags and HTML escapes. It is no longer
necessary to use the HTML <code>
or
<tt> tags in doc
comments: the Javadoc {@code}
tag
is preferable because it
eliminates the need to escape HTML metacharacters.
Finally,
notice the use of the word “this” in the doc comment. By convention, the word
“this” always refers to the object on which the method is invoked when it is
used in the doc comment for an instance method.
The best way
to get these characters into documentation is to surround them with the {@literal} tag, which suppress processing of HTML markup
and nested Javadoc tags. It is like the {@code}
tag,
except that it doesn’t render the text in code font. For example, this Javadoc
fragment:
* The triangle inequality is {@literal |x + y| < |x|
+ |y|}.
produces the
documentation: “The triangle inequality is |x + y| < |x| + |y|.”
To avoid
confusion, no two members or constructors in a class or interface should have
the same summary description.
For methods
and constructors, the summary description should be a full verb phrase
(including any object) describing the action performed by the method. For
example,
• ArrayList(int initialCapacity)—Constructs an
empty list with the specified initial capacity.
• Collection.size()—Returns the number of elements in this
collection.
For classes,
interfaces, and fields, the summary description should be a noun phrase
describing the thing represented by an instance of the class or interface or by
the field itself. For example,
• TimerTask—A task that can be scheduled for one-time or
repeated execution by a Timer.
• Math.PI—The double
value
that is closer than any other to pi, the ratio of the circumference of a circle
to its diameter.
Three features
added to the language in release 1.5 require special care in doc comments:
generics, enums, and annotations. When documenting a generic type or method, be
sure to document all type parameters:
/**
* An object that maps keys to values. A map cannot
contain
* duplicate keys; each key can map to at most one value.
*
* (Remainder omitted)
*
* @param <K> the type of keys maintained by
this map
* @param <V> the type of mapped values
*/
public interface Map<K,
V> {
... // Remainder omitted
}
When documenting
an enum type, be sure to document the constants as well as the
type and any public methods. Note that you can put an entire doc comment on one
line if it’s short:
/**
* An instrument section of a symphony orchestra.
*/
public enum OrchestraSection {
/** Woodwinds, such as flute, clarinet, and oboe. */
WOODWIND,
/** Brass instruments, such as french horn and
trumpet. */
BRASS,
/** Percussion instruments, such as timpani and
cymbals */
PERCUSSION,
/** Stringed instruments, such as violin and cello.
*/
STRING;
}
When documenting
an annotation type, be sure to document any members as well as the
type itself. Document members with noun phrases, as if they were fields. For
the summary description of the type, use a verb phrase that says what it means
when a program element has an annotation of this type:
/**
* Indicates that the annotated method is a test method
that
* must throw the designated exception to succeed.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
* The exception that the annotated test method must
throw
* in order to pass. (The test is permitted to throw any
* subtype of the type described by this class object.)
*/
Class<? extends Exception> value();
}
As of release
1.5, package-level doc comments should be placed in a file called package-info.java instead of package.html. In addition
to packagelevel doc comments, package-info.java
can
(but is not required to) contain a package declaration and package annotations.
Javadoc has
the ability to “inherit” method comments. If an API element does not have a doc
comment, Javadoc searches for the most specific applicable doc comment, giving
preference to interfaces over superclasses. The details of the search algorithm
can be found in The Javadoc Reference Guide [Javadoc-ref].
You can also inherit parts of doc comments from supertypes
using the {@inheritDoc} tag.
A simple way
to reduce the likelihood of errors in documentation comments is to run the HTML
files generated by Javadoc through an HTML validity
checker.
This will detect many incorrect uses of HTML tags, as well as HTML
metacharacters that should have been escaped. Several HTML validity checkers
are available for download and you can validate HTML online [W3C-validator].
The
conventions described in this item cover the basics. The definitive guide to
writing doc comments is Sun’s How to Write Doc
Comments [Javadoc-guide].
There are IDE plug-ins that check for adherence to many of these rules [Burn01].
To summarize,
documentation comments are the best, most effective way to document your API.
Their use should be considered mandatory for all exported API elements. Adopt a
consistent style that adheres to standard conventions. Remember that arbitrary
HTML is permissible within documentation comments and that HTML metacharacters
must be escaped.
Reference: Effective Java 2nd Edition by Joshua Bloch
