Annotations

Java Programming Javadoc

Annotations/Introduction

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

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. */publicclassExample{/** ...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 (@):

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. */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:

See alsoannotations since Java 5.

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 namedExample defined in a package namedorg.wikibooks.en in the fileC:\ProgJava\org\wikibooks\en\Example.java :

Code listing 8.2: Example.java packageorg.wikibooks.en;/** * An example class. */publicclassExample{/** 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:

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 namedpackage.html which should be placed in the given folder. In our example, we should document the package in the fileC:\ProgJava\org\wikibooks\en\package.html.

Since Java 5^[1], thepackage.html file can be replaced by a special Java file namedpackage-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>. */packageorg.wikibooks.en;

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

To do: Add some exercises like the ones inVariables.

Annotations

Java Programming Javadoc

Annotations/Introduction

• Book:Java Programming

• Pages using the JsonConfig extension
• Wikibooks pages with to-do lists