# Java Programming/Javadoc

* Navigate Javadoc & Annotations topic: ( v • d • e )
* Javadoc
* Introduction to Annotation
* Creating custom annotations
* Meta-annotations
* Helping the compiler
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.
* Code listing 8.1: Example.java
* * A class to give an <b>example</b> of HTML documentation.
* public class Example {
* /** ...Documentation of a member with the type integer named example... */
* public int example;
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 (@):
* Code section 8.1: Documentation comment.
* * Get the sum of two integers.
* * @param a The first integer number.
* * @param b The second integer number.
* * @return The value of the sum of the two given integers.
* public int sum(int a, int b) {
* return a + b;

### Get the sum of two integers.

    Description of the sum method.

### @param a The first integer number.

    Description attribute of the parameter a of the method.

### @param b The second integer number.

    Description attribute of the parameter b of the method.

### @return The value of the sum of the two given integers.

    Description attribute of the value returned by the method.
Here is a non exhaustive list of special attributes:
| Attribute and syntax | In a comment of ... | Description |
| @author author | class | Name of the author of the class. |
| @version version | class | Version of the class. |
| @deprecated description | class, constructor, method, field | Flags the entity as deprecated (old version), describes why and by what replace it. If the entity flagged as deprecated by this attribute is used, the compiler give a warning. |
| @see reference | class, constructor, method, field | Add a link in the section "See also". |
| @param id description | constructor and method | Describes the method parameter. |
| @return description | method | Describes the value returned by the method. |
| @exception type description | constructor and method | Describes the reason of the throw of an exception of the specified type (throws clause). |
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 Example defined in a package named org.wikibooks.en in the file C:\ProgJava\org\wikibooks\en\Example.java :
* Code listing 8.2: Example.java
* package org.wikibooks.en;
* * An example class.
* public class Example {
* Get the sum of two integers.
* @param a The first integer number.
* @param b The second integer number.
* @return The value of the sum of the two given integers.
* public int sum(int a, int b) {
* return a + b;
The documentation can be generated in a specific folder (C:\ProgDoc for example) with the following command:
* Command 8.1: Documentation generation
* $ javadoc -locale en_US -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.wikibooks.en
The options of this command are described below:

### -locale en_US

    The documentation in US English.

### -use

    Create the pages about the use of the classes and the packages.

### -classpath C:\ProgJava

    The path of the compiled classes (*.class).

### -sourcepath C:\ProgJava

    The path of the source classes (*.java).

### -d C:\ProgDoc

    The path where the documentation must be generated.

### org.wikibooks.en

    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 package.html which should be placed in the given folder. In our example, we should document the package in the file C:\ProgJava\org\wikibooks\en\package.html.
Since Java 5, the package.html file can be replaced by a special Java file named package-info.java containing only the package declaration preceding by a documentation comment.
* Code listing 8.3: C:\ProgJava\org\wikibooks\en\package-info.java
* * This fake package is used to illustrate the Java wikibook.
* * at <i>en.wikibooks.org</i>.
* package org.wikibooks.en;

## References

* ↑ http://docs.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.html#packagecomment