Javadoc
Java allows users to document the classes and the members by using a particular syntax of comment.
Syntax
[edit | edit source ]A documentation comment is framed by slash-star-star and star-slash (i.e. /** ... */). The documentation is in the HTML format.
/** * A class to give an <b>example</b> of HTML documentation. */ publicclass Example{ /** ...Documentation of a member with the type integer named example... */ publicintexample; }
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 (@):
/** * 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. */ publicintsum(inta,intb){ returna+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 | edit source ]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
:
packageorg.wikibooks.en; /** * An example class. */ publicclass 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. */ publicintsum(inta,intb){ returna+b; } }
The documentation can be generated in a specific folder (C:\ProgDoc for example) with the following command:
$ 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.
/** * This fake package is used to illustrate the Java wikibook. * at <i>en.wikibooks.org</i>. */ packageorg.wikibooks.en;
References
[edit | edit source ]
To do:
Add some exercises like the ones in Variables.