Javadoc

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 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 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 Override location of installed extensions -verbose Output messages about what Javadoc is doing -locale Locale to be used, e.g. en_US or en_US_WIN -encoding Source file encoding name -J Pass directly to the runtime system Provided by Standard doclet: -d 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 Browser window title for the documenation -doctitle Include title for the package index(first) page -header Include header text for each page -footer Include footer text for each page -bottom Include bottom text for each page -link Create links to javadoc output at -linkoffline Link to docs at using package list at -group :.. 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 for cross-platform viewing of generated documentation. -helpfile Include file that help link links to -stylesheetfile <path> File to change style of the generated documentation -docencoding Output encoding name