Javadoc
| Navigate Javadoc & Annotations topic: |
Java allows users to document the classes and the members by using a particular syntax of comment.
Syntax edit
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 edit
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[1], 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 edit
