Java Programming/Javadoc

Java allows users to document the classes and the members by using a particular syntax of comment.

Syntax
A documentation comment is framed by slash-star-star and star-slash (i.e. /** ... */). The documentation is in the HTML format.

A documentation comment is placed just above the commented entity (class, constructor, method, field).

In a documentation comment, the first part is a description text in the HTML format. The second part is a list of special attributes whose name starts with an at sign (@):


 * : Description of the sum method.
 * : Description attribute of the parameter a of the method.
 * : Description attribute of the parameter b of the method.
 * : Description attribute of the value returned by the method.

Here is a non exhaustive list of special attributes:

See also annotations since Java 5.

Documentation
The JDK provides a tool named javadoc which allows to generate the documentation of the well commented classes. The javadoc command without argument give the complete syntax of the command.

Example : for a class named  defined in a package named   in the file   :

The documentation can be generated in a specific folder (C:\ProgDoc for example) with the following command:

The options of this command are described below:
 * : The documentation in US English.
 * : Create the pages about the use of the classes and the packages.
 * : The path of the compiled classes (*.class).
 * : The path of the source classes (*.java).
 * : The path where the documentation must be generated.
 * : The name of the package to document. It is possible to specify several packages, or one or several class names to document only those ones.

The description page of a package copy the description text from the file named  which should be placed in the given folder. In our example, we should document the package in the file.

Since Java 5, the  file can be replaced by a special Java file named   containing only the package declaration preceding by a documentation comment.