CS 24L Object-Oriented Programming

[Home]

Here is a link to a javadoc Tutorial.

The javadoc Tool

The pupose of the javadoc tool is the generation of API documentation in the HTML format. The information for the documentation is obtained directly from the code and any embedded document comments. This page introduces you to some of the more important and easy to use javadoc options. However, for more information go to the Java web site.

The javadoc tool is a command line driven one with the following command format.

javadoc [ options ] [ package-names ] [ source-files ] [ @files ]

The arguments may be in any order and are briefly described below.
 
 
Argument
Description
options Various options used to control the document generation process.
package-names The list of packages that you wish to document. Each package name is separated by a space.
source-files The list of source files that you wish to document. Each name is separated by a space.
@files One or more text files that contain the names of the packages and source files that you wish to document.

Options

The javadoc tool provides a considerable number of options for controlling the document generation process. Only a few of these options are described below. For more information, go to the Java web site.
 
Option
Description
-author Includes the text for the @author tags.
-d directory This is the directory where the generated HTML files will be saved. When this option is not used, the HTML files are placed in the current directory.
-verbose The messages displayed by javadoc during processing will be more detailed than the default.
-version Includes the text for the @version tag.

Source Files

There are several methods for stating the classes to be documented. Firstly and possibly the easiest method, is to go to the directory containing the code and then activate the javadoc utility from there. For example,

c:\> cd mycode
c:\mycode> javadoc Demo.java Test.java R*.java

In this example, the classes Demo.java, Test.java and all classes that start with R are documented. Notice that the user first changed the working directory to c:\mycode before executing the javadoc utility.

Another method is to specify the full path of the classes to be compiled.

c:\temp> javadoc c:\mycode\Demo.java c:\mycode\Test.java c:\mycode\R*.java

The same classes are being documented but in this case, the user is in the directory c:\temp and so has to enter the full path.

File Lists

To reduce the amount of typing that one needs to perform at the command line prompt. The javadoc utility provides an option for passing the names of text files that themselves contain lists of files that will be used in the documentation process. Assume that the following information is entered into a text file called mylist.

c:\mycode\Demo.java
c:\mycode\Test.java
c:\mycode\R*.java

Then the following command can be invoked.

c:\temp> javadoc @mylist

All of the classes listed in the file mylist will be processed. Note that more than one of these special files can stated as long as each begins with the @ character.

Copyright © 1999-2003, Colin Depradine. All rights reserved.