Here's a list of details that should be specified for each API (either explicitly or implicitly) in the API reference documentation:

For related information, see How to Write Doc Comments for Javadoc.

Class/Interface

• Purpose of class
  • What's it useful for?
  • How is it used? (for instantiating, subclassing)
  • How does it work?
• Class definition
  • modifiers: abstract, final, public
  • extends class
  • implements interfaces
• Instantiating class
  • How to instantiate the class, including setup required
  • What other classes are automatically created as a result
• Subclassing class
  • When to subclass the class
  • What methods must be overridden
• Freeing an instance
  • Any references to instance that must be freed
• Example

Method/Constructor

• Purpose of method
  • What is it useful for?
  • How is it used?
  • How does it work?
  • Does it work by return value, side effect or both?
• Method definition
  • static (class method / instance method)
  • access (public/protected/friendly/private)
  • Number and type of arguments
  • Type of return value
  • abstract (abstract/concrete)
  • final (unredefinable/redefinable)
  • synchronized (omit - see NOTE 1)
  • native (omit - see NOTE 1)
  • throws (exceptions)
• Method call
  • Whether the method is implicitly or explicitly called in code
  • How to call the method
  • Valid range of each argument
  • Valid range of return values
  • Side effects of method
• Method overriding
  • Does it override a method in a superclass?
  • Can it be overridden in a subclass? (final)
• Example

NOTE 1 - "synchronized" and "native" - There is agreement that these two keywords should not appear in the API specs as part of the Java API Platform standard. These are implementation details which should be documented in other ways. For example, a method that must be synchronized could be documented as follows:

APIs should document their concurrency semantics (as in "a single Enumeration cannot be used by multiple threads concurrently") but not how they achieve these semantics. For example, even assuming that Hashtable should be thread-safe, there's no reason that we should tell people that we're achieving this by synchronizing all of its exported methods. We should reserve the right to synchronize internally at the bucket level, thus offering higher concurrency. (Geeks take note: the auto-grow functionality of Hashtables may prevent us from taking advantage of this specific suggestion, but you get the idea.)

The Java API books (Vol 1 & 2) were done this way. The Javadoc- generated HTML and the Java Class Libraries include "synchronized".

Field

• Purpose of field
  • What's it useful for?
• Field definition
  • static (class variable / instance variable)
  • type
  • final (constant/variable)
  • transient (transient/persistent)
  • volatile
  • read/write
• Example
  • (fields are usually too simple to require example)