The backed up content of this page is deprecated and will not be included in search results!

This page has been moved to the new HttpComponents Wiki.

HttpClient 4.0 Javadoc guidelines:

Interface description must consist of

• Purpose

• Description (optional)

• Statement whether this interface represents an entity or a process defined by a standard specification such as RFC document, when applicable (optional)

Class description must consist of

• Purpose

• Description (optional)

• Statement whether this class implements an entity or a process defined by a standard specification such as RFC document, when applicable (optional)

• Statement whether instances of this class are mutable (optional). If not explicitly stated, instances of this class are assumed to be mutable

• Statement whether this class is multi-threading safe (optional). If not explicitly stated, the class is assumed to be NOT threading-safe

Method description must consist of

• Purpose

• Expected effect

• Description (optional)

• Statement whether this method is modal, that is, if the object must be in a specific state (pre-conditions) or mode in order to execute correctly (optional). If not explicitly stated, the method is assumed to be non-modal.

• Required parameters. It must be explicitly stated whether null is permitted as a parameter value. Per default parameters are assumed to require a non-null value and to cause a  IllegalArgumentException  if null is given.

• Exceptions that can be thrown in the course of method's execution and their possible cause (post-conditions).

• private methods can have minimal or no JavaDoc if they are short and trivial enough.

• methods that implement a signature from an interface or base class that is sufficiently documented there can omit JavaDocs in favor of comments like:

   // non-javadoc, see interface XXX 

   // non-javadoc, see class XYZ 

  The non-javadoc comment with a pointer to the documentation is required for people reading the source code. The JavaDoc tool will automatically copy the description from the interface or base class into the generated documentation.