Purpose

The method must document its goal, not how the goal is achieved (in ordinary cases, please refer to the section Implementation for details).

Preconditions

The preconditions of the method must be documented by either

• the documentation of the individual parameters,
• the throws documentation of runtime exceptions that will be thrown, if the preconditions are violated
• or both.

The following shows the checking of the precondition posed on the arguments of a constructor call:

/**
 * Default constructor.
 *
 * @param location the location of the issue. The location may be
 *         <code>null</code> if the location of the issue cannot be
 *          determined.
 * @param message the message text of the message.
 * @throws NullPointerException if the <code>message</code> is
 *           <code>null</code>.
 * @throws IllegalArgumentException if the message is the empty string or
 *           contains only whitespaces.
 */
public IssueMessage(final IssueLocation location, final String message)
   throws NullPointerException, IllegalArgumentException {
   checkArguments(location, message);
   this.location = location;
   this.message = message;
}

Postconditions

A method should document the conditions on the instance or manipulated parameters after the method completes successfully.

Side Effects

A method should document side effects that may be relevant to the client of the method. This includes accessing resources (such as files or database connections) or if the method manipulates the instance. Both must only be documented if the side effect is not clear from the context (a method "readFile" is clearly accessing a file, a method "setName" is clearly changing the state of the instance).

Exceptions

We are supporters of the concept of documenting checked and unchecked exceptions. The phrase describing the condition when the exception is thrown should start with if.

@throws IllegalArgumentException if the message is the empty string or
          contains only whitespaces.

Overloading Methods

Overloading methods should make clear in the first sentence how they differ from their colleagues. This is important since the first sentence is rendered in the index of the Javadoc report.

Because constructors overload other constructors naturally, this holds true for constructors as well.

The following example is taken from java.io.PrintStream.

/**
 * Print a boolean value.  ...
 */
public void print(boolean b) {
	...

/**
 * Print a character.  ...
 */
public void print(char c) {
	...

/**
 * Print an integer.  ...
 */
public void print(int i) {
	...

Implementation

In some cases the implementation of a method may be relevant to be documented in the Javadoc. This is the case where multiple implementations of an interface are provided (e.g. for collection classes).

Consider using the @impl tag of the Taglets library for documenting the implementation details.

/**
 * ...
 *
 * @impl Description of an implementation detail.
 */