Documentation Comments Core Java

The JDK contains a very useful tool, called javadoc, that generates HTML documentation from your source files. In fact, the on-line API documentation is simply the result of running javadoc on the source code of the standard Java library.

If you add comments that start with the special delimiter /** to your source code, youtoo can easily produce professional-looking documentation. This is a very nice schemebecause it lets you keep your code and documentation in one place. If you put your documentation into a separate file, then you probably know that the code and commentstend to diverge over time. But because the documentation comments are in the same fileas the source code, it is an easy matter to update both and run javadoc again.

Comment Insertion

The javadoc utility extracts information for the following items:

  • Packages
  • Public classes and interfaces
  • Public and protected methods
  • Public and protected fields

You can (and should) supply a comment for each of these features. Each comment isplaced immediately above the feature it describes. A comment starts with a /** and endswith a */.

Each/** ... */documentation comment contains
free-form text
followed by tags.

A tagstarts with an @, such as @author or @param. The first sentence of the free-form text should be a summary statement. The javadoc utility automatically generates summary pages that extract these sentences.

In the free-form text, you can use HTML modifiers such as <em>...</em> for emphasis,<code>...</code> for a monospaced “typewriter” font, <strong>...</strong> for strong emphasis,and even <img ...> to include an image. You should, however, stay away from headings<h1> or rules <hr> because they can interfere with the formatting of the document.

NOTE: If your comments contain links to other files such as images (for example, diagrams or images of user interface components), place those files into a subdirectory of the directory containing the source file named doc-files. The javadoc utility will copy the docfiles directories and their contents from the source directory to the documentation directory. You need to use the doc-files directory in your link, such as <imgsrc="doc-files/ uml .png" alt= "UML diagram"/>.

Class Comments

The class comment must be placed after any import statements, directly before the class definition.

Here is an example of a class comment:

NOTE: There is no need to add an * in front of every line. For example, the following comment is equally valid:

However, most IDEs supply the asterisks automatically and rearrange them when the line breaks change.

Method Comments

Each method comment must immediately precede the method that it describes. In additionto the general-purpose tags, you can use the following tags:

  • @paramvariable description
    This tag adds an entry to the “parameters” section of the current method. The description can span multiple lines and can use HTML tags. All @param tags for one method must be kept together.
  • @return description
    This tag adds a “returns” section to the current method. The description can spanmultiple lines and can use HTML tags.
  • @throws class description
    This tag adds a note that this method may throw an exception

Here is an example of a method comment:

Field Comments

You only need to document public fields—generally that means static constants. For example:

General Comments

The following tags can be used in class documentation comments:

  • @author name
    This tag makes an “author” entry. You can have multiple @author tags, one for eachauthor.
  • @version text
    This tag makes a “version” entry. The text can be any description of the currentversion.
  • The following tags can be used in all documentation comments:
  • @since text
    This tag makes a “since” entry. The text can be any description of the version thatintroduced this feature. For example, @since version 1.7.1
  • @deprecated text
    This tag adds a comment that the class, method, or variable should no longer beused. The text should suggest a replacement. For example:
  • @deprecated Use <code>setVisible(true)</code> instead You can use hyperlinks to other relevant parts of the javadoc documentation, or to externaldocuments, with the @see and @link tags.
  • @see reference
    This tag adds a hyperlink in the “see also” section. It can be used with both classesand methods. Here, reference can be one of the following:

The first case is the most useful. You supply the name of a class, method, or variable, and javadoc inserts a hyper link to the documentation. For example,

@see com.horstmann.corejava.Employee#raiseSalary(double)

makes a link to the raiseSalary(double) method in the com .horstmann .corejava .Employee class. You can omit the name of the package or both the package and class name.Then, the feature will be located in the current package or class.

Note that you must use a #, not a period, to separate the class from the method orvariable name. The Java compiler itself is highly skilled in guessing the various meanings of the period character, as separator between packages, sub packages, classes, inner classes, and methods and variables. But the javadoc utility isn’t quite asclever, and you have to help it along.

If the @see tag is followed by a < character, then you need to specify a hyperlink. You

can link to any URL you like. For example:

@see <a href="www.horstmann.com/corejava.html"> The Core Java home page</a>

In each of these cases, you can specify an optional label that will appear as the linkanchor. If you omit the label, then the user will see the target code name or URL asthe anchor.

If the @see tag is followed by a " character, then the text is displayed in the “see also”section. For example:

@see "Core Java 2 volume 2"

You can add multiple @see tags for one feature, but you must keep them all together.

  • If you like, you can place hyperlinks to other classes or methods anywhere in any of

your documentation comments. You insert a special tag of the form

{@link package.class#feature label}

anywhere in a comment. The feature description follows the same rules as for the

@see tag.

Package and Overview Comments

You place class, method, and variable comments directly into the Java source files, elimited by /** . . . */ documentation comments. However, to generate package comments, you need to add a separate file in each package directory. You have two choices:

  1. Supply an HTML file named package.html. All text between the tags <body>...</body> isextracted.
  2. Supply a Java file named package-info.java. The file must contain an initial Javadoccomment, delimited with /** and */, followed by a package statement. It should containno further code or comments.

You can also supply an overview comment for all source files. Place it in a file calledoverview.html, located in the parent directory that contains all the source files. All textbetween the tags < body>...< /body> is extracted. This comment is displayed when the userselects “Overview” from the navigation bar.

Comment Extraction

Here, docDirectoryis the name of the directory where you want the HTML files to go. Follow

these steps:

  1. Change to the directory that contains the source files you want to document. Ifyou have nested packages to document, such as com .horstmann .corejava, you must be working in the directory that contains the sub directory com. (This is the directory that contains the overview .html file if you supplied one.)
  2. Run the command
javadoc -d docDirectorynameOfPackage for a single package. Or run javadoc -d docDirectory nameOfPackage1 nameOfPackage2...

to document multiple packages. If your files are in the default package, then instead run

If you omit the -d docDirectory option, then the HTML files are extracted to the current directory. That can get messy, and we don’t recommend it.

The javadoc program can be fine -tuned by numerous command -line options. For example, you can use the -author and -version options to include the @author and @version tags in the documentation. (By default, they are omitted.) Another useful option is -link, to include hyperlinks to standard classes. For example, if you use the command

all standard library classes are automatically linked to the documentation on the Sunweb site.

If you use the -linksource option, each source file is converted to HTML (without color coding, but with line numbers), and each class and method name turns into a hyperlinkto the source.

NOTE: If you require further customization, for example, to produce documentation in a format other than HTML, you can supply your own docletto generate the output in any form you desire. Clearly, this is a specialized need, and we refer you to the on-line documentation for details on doclets at .

TIP: A useful doclet is DocCheck at. It scans a set of source files for missing documentation comments.


Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

Core Java Topics