Page Comparison

...

Format is not as important as content, but it is desirable to have a consistent standard across the project so that people know what to expect. Elements of a javadoc should be present in the following order:

/**
 * Summary fragment.
 *
 * Additional descriptive text.
 *
 * @param
 * @return
 * @throws
 * @deprecated
 */

...

The summary fragment is a required description of what the class or method does. It is a fragment, meaning it is not a complete sentence. The first word should be capitalized .

Instantiable Types

Methods

Additional Descriptive Text

and the fragment should end with a period.

Classes

Anything that can be instantiated should be described as a noun. For example:

A service that manages the lifecycle of programs.

and not:

Manages the lifecycle of programs.

Methods

Methods should be described as a verb. In other words, treat is like there is an implicit 'This method ...' in front of the summary fragment. For example:

Validates the specified program options and starts the program if they are valid. 

Additional Descriptive Text

A summary fragment is often not enough for a reader to understand the full behavior of the API. Any additional details after the fragment should be in complete, grammatically correct sentences.

It is a good place to put clarifying examples, notes about performance, warnings about misusing the API, and any other information that might not fall under common usage patterns.

If a method modifies state, the additional descriptive text should mention what state is modified.

If the method throws exceptions, 

At-clauses

Every at-clause should be followed by a fragment as a description. By convention, the fragment should not be capitalized and should not be a complete sentence. If the fragment is all that is needed, it should not contain a period at the end. For example:

...

Every method argument should be documented with its own @param clause. Multiple @param clauses should appear in same order that they appear in the method signature. If some instances or values for that parameter are not valid input, they must be documented. Similarly, if the parameter can be null, the behavior for a null value must be documented. For example:

@param limit the maximum number of results to return

is not a good javadoc because it does not address what happens if the limit is 0 or below. Does the method throw an exception? Does it do something else? A better javadoc would be:

@param limit the maximum number of results to return. If the limit is equal to or less than 0, no limit will be applied. 

...