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.

Computer code Code listing 8.1:
1 /**
2  *  A class to give an <b>example</b> of HTML documentation.
3  */
4 public class Example {
5     /** ...Documentation of a member with the type integer named example... */
6     public int example;
7 }

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 (@):

Example Code section 8.1: Documentation comment.
1 /**
2  *  Get the sum of two integers.
3  *  @param a The first integer number.
4  *  @param b The second integer number.
5  *  @return The value of the sum of the two given integers.
6  */
7 public int sum(int a, int b) {
8     return a + b;
9 }
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.


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.Study Guides.en in the file C:\ProgJava\org\Study Guides\en\ :

Computer code Code listing 8.2:
 1 package org.Study Guides.en;
 3 /**
 4  *  An example class.
 5  */
 6 public class Example {
 7     /**
 8     Get the sum of two integers.
 9     @param a The first integer number.
10     @param b The second integer number.
11     @return The value of the sum of the two given integers.
12     */
13     public int sum(int a, int b) {
14         return a + b;
15     }
16 }

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

Standard input or output Command 8.1: Documentation generation
$ javadoc -locale en_US -use -classpath C:\ProgJava -sourcepath C:\ProgJava -d C:\ProgDoc org.Study Guides.en

The options of this command are described below:

-locale en_US
The documentation in US English.
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.Study Guides.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\Study Guides\en\package.html.

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

Computer code Code listing 8.3: C:\ProgJava\org\Study Guides\en\
1 /**
2  * This fake package is used to illustrate the Java Study Guide.
3  * at <i>en.Study</i>.
4  */
5 package org.Study Guides.en;


  1. ?


To do:
Add some exercises like the ones in Variables.

  This article uses material from the Wikipedia page available here. It is released under the Creative Commons Attribution-Share-Alike License 3.0.



Connect with defaultLogic
What We've Done
Led Digital Marketing Efforts of Top 500 e-Retailers.
Worked with Top Brands at Leading Agencies.
Successfully Managed Over $50 million in Digital Ad Spend.
Developed Strategies and Processes that Enabled Brands to Grow During an Economic Downturn.
Taught Advanced Internet Marketing Strategies at the graduate level.

Manage research, learning and skills at defaultLogic. Create an account using LinkedIn or facebook to manage and organize your Digital Marketing and Technology knowledge. defaultLogic works like a shopping cart for information -- helping you to save, discuss and share.

Visit defaultLogic's partner sites below: : Music Genres | Musicians | Musical Instruments | Music Industry
NCR Works : Retail Banking | Restaurant Industry | Retail Industry | Hospitality Industry

  Contact Us