Javadoc

Tools Practice

One of the more useful tools in the JDK toolkit is javadoc. This tool is used
to produce documentation pages from comments embedded within our Java
programs. The document pages are automatically produced in HTML with a
distinctive style that has come to be associated with Java documentation. In
order to use javadoc, we must first embed special comments within our
program. These comments have the form:

/** This is a comment .........................

...and here is line two of the comment*/

The comment begins with “/**” and ends (as do all comment blocks) with
“*/”. We associate these blocks with specific parts of our .java file by
placing the special comment block directly before that part of the code.

Blocks can be associated with:

The class, itself,

public, or otherwise accessible instance variables, or
specific methods of the class.

The general form for a .java file with javadoc comments is as follows:

/** This is a comment associated with the class */

public class MyClass {
/** This block is associated with an instance variable */
public int xxx;

/**This comment is associated with a method */

public void myMethod () {
...
The following program illustrates several of the javadoc tags and features.
We can run javadoc with the following command:

javadoc -version -author DocDemo.java

...and this will produce a set of documentation in HTML format.

A brief synopsis of the javadoc command can be obtained by executing the

command “javadoc” alone and without specifying any input parameters. The
resulting error message lists the command’s options and parameters:
usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
-overview <file> Read overview documentation from HTML file
-public Show only public classes and members
-protected Show protected/public classes and members (default)
-package Show package/protected/public classes and members
-private Show all classes and members
-help Display command line options
-doclet <class> Generate output via alternate doclet
-docletpath <path> Specify where to find doclet class files
-1.1 Generate output using JDK 1.1 emulating doclet
-sourcepath <pathlist> Specify where to find source files
-classpath <pathlist> Specify where to find user class files
-bootclasspath <pathlist> Override location of class files loaded
by the bootstrap class loader
-extdirs <dirlist> Override location of installed extensions
-verbose Output messages about what Javadoc is doing
-locale <name> Locale to be used, e.g. en_US or en_US_WIN
-encoding <name> Source file encoding name
-J<flag> Pass <flag> directly to the runtime system

Provided by Standard doclet:

-d <directory> Destination directory for output files
-use Create class and package usage pages
-version Include @version paragraphs
-author Include @author paragraphs
-splitindex Split index into one file per letter
-windowtitle <text> Browser window title for the documenation
-doctitle <html-code> Include title for the package index(first) page
-header <html-code> Include header text for each page
-footer <html-code> Include footer text for each page
-bottom <html-code> Include bottom text for each page
-link <url> Create links to javadoc output at <url>
-linkoffline <url> <url2> Link to docs at <url> using package list at <url2>
-group <name> <p1>:<p2>.. Group specified packages together in overview page
-nodeprecated Do not include @deprecated information
-nosince Do not include @since information
-nodeprecatedlist Do not generate deprecated list
-notree Do not generate class hierarchy
-noindex Do not generate index
-nohelp Do not generate help link
-nonavbar Do not generate navigation bar
-serialwarn Generate warning about @serial tag
-charset <charset> Charset for cross-platform viewing of generated
documentation.
-helpfile <file> Include file that help link links to
-stylesheetfile <path> File to change style of the generated documentation
-docencoding <name> Output encoding name