Item 44 - Write doc comments for all exposed API elements

From Effective Java 2/e by Joshua Bloch

Javadoc generates API documentation automatically from source code with specially formatted documentation comments, more commonly known as doc comments
The Javadoc utility translates doc comments into HTML
How to write doc comments

/**
 * Returns the element at the specified position in this list. *
 * 
This method is not 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);
  • The doc comment for a method should describe succinctly the contract between the method and its client
    • 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
  • Methods should document any side effects
  • 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
    • @param tag or @return tag should be a noun phrase describing the value represented by the parameter or return value
    • @throws tag should consist of the word “if,” followed by a clause describing the conditions under which the exception is thrown
    • @param, @return, or @throws tag is not terminated by a period

Javadoc {@code} tag * Eliminates the need to escape HTML meta characters

Javadoc {@literal} tag * Like the {@code} tag, except that it doesn’t render the text in code font

Summary description * The first “sentence” of each doc comment (as defined below) becomes the summary description of the element * 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 

   ArrayList(int initialCapacity) — Constructs an empty list with the spec- ified 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 
   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.

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
}

Enum type
Be sure to document the constants

/**
 * 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;
}

Annotation type
Be sure to document any members

/**
 * 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();
}

Caveat

  • As of release 1.5, package-level doc comments should be placed in a file called package-info.java
  • Whether or not a class is thread-safe, you should document its thread-safety level
  • If a class is serializable, you should document its serialized form
  • Javadoc has the ability to “inherit” method comments
    • 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
  • While it is necessary to provide documentation comments for all exported API elements, it is not always sufficient. For complex APIs consisting of multiple interrelated classes, it is often necessary to supplement the documentation comments with an external document describing the overall architecture of the API

Posted by The Finest Artist