Effective Java 44 Write doc comments for all exposed API elements

Principle

1. You must precede every exported class, interface, constructor, method, and field declaration with a doc comment.
2. If a class is serializable, you should also document its serialized form (Item 75).
3. To write maintainable code, you should also write doc comments for most unexported classes, interfaces, constructors, methods, and fields.
4. What comment to doc

   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.

   • Happypath

   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.

   • Exception path

   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.

   • Side effects

   An observable change in the state of the system that is not obviously required in order to achieve the postcondition. For example, if a method starts a background thread, the documentation should make note of it.

   • Thread safety

   Describe the thread safety of a class or method, as discussed in Item 70.

5. Tag description
   • @param - a noun phrase describing the value represented by parameter.
   • @return - a noun phrase describing the value represented by return value.
   • @throws - consist of the word "if", followed by a clause describing the conditions under which the exception is thrown. Occasionally, arithmetic expressions are used in place of noun phrases.
   • {@code} - 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.

     precede the multiline code example with the characters <pre>{@code and follow it with the characters }</pre>.

   /**

   * 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);

   • Use the word "this" always to refers to the object on which the method is invoked when it is used in the doc comment for an instance method.
   • {@literal} - suppress processing of HTML markup and nested Javadoc tags. Unlike {@Code} tag it doesn't render the test in code font.

   * The triangle inequality is {@literal |x + y| < |x| + |y|}.

   produces the documentation: "The triangle inequality is |x + y| < |x| + |y|."

6. Doc comments should be readable in both the source code and in the generated documentation. If you can't achieve both, generated documentation readability trumps source code readability.
7. No two members or constructors in a class or interface should have the same summary description.
8. If the intended summary description contains a period , because the period can prematurely terminate the description.

   /**

   * A college degree, such as B.S., {@literal M.S.} or Ph.D.

   * College is a fountain of knowledge where many go to drink.

   */

   public class Degree { ... }

9.  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 specified initial capacity.

• Collection.size()—Returns the number of elements in this collection.

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

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

}

12.  When documenting an enum type, be sure to document the constants as well as the type and any public methods.

/**

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

}

13.  When documenting an annotation type, be sure to document any members as well as the type itself.  

/**

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

}

14.  If a class is serializable, you should document its serialized form, as described in Item 75.

15.  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. You can also inherit parts of doc comments from super types using the {@inheritDoc} tag.

16.  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. If such a document exists, the relevant class or package documentation comments should include a link to it.  

Summary

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 meta characters must be escaped.