Java Reference
In-Depth Information
Appendix B
Documentation Comments
The Java programming language lets you include comments in the source code that can be used to prepare
documentation for the application. Such comments are known as documentation comments or Javadoc comments. JDK
provides a
javadoc
command-line tool to extract the documentation comments from the source codes and generate
documentation in HTML format. The
javadoc
tool is located in the
bin
directory of the
JDK_HOME
directory. For example,
if you have installed the JDK in
C:\java8
directory, the
javadoc
tool will be located in the
C:\java8\bin
directory.
Although a documentation comment can appear anywhere in Java source code, the
javadoc
tool uses only those
documentation comments to generate the HTML pages that appear just before the declaration of classes, nested
classes, interfaces, enums, annotations, constructors, methods, and fields. Note that the tool does not generate
documentation for the documentation comments that are written for anonymous classes, package declarations, and
import declarations. You need to write the documentation comments in a separate special file for a package, which
will be used by the tool to generate documentation for that package.
A documentation comment starts with
/**
characters and ends with
*/
characters. The leading asterisks (
*
) on
each line of the documentation comment are ignored. The following is an example of a documentation comment that
is written for the
Calc
class declaration:
// Calc.java
package com.jdojo.utility;
/**
* A utility class to perform basic calculations on numbers. All
* methods in this class are <code>static</code>. It provides methods
* to perform addition, subtraction, multiplication, and division.
*
* @author Kishori Sharan
*/
public final class Calc {
// Code for Calc class goes here
}
It is important to note that the documentation comment must appear just before the declaration of the program
element for which it is intended. Otherwise, it will be ignored by the
javadoc
tool, or shown for the wrong element.
The following two documentation comments are not the same:
/* Example #1 */
/**
* This documentation comment is intended for the class declaration
* Xyz. However, it will be ignored by the javadoc tool, because there
* is a package declaration between this documentation comment and the
