< Zurück | Inhalt | Weiter >

5.5.2 Javadoc Command-Line Options

As with other options documentation in this chapter, this is not intended to be a complete reference document. We are documenting only the most impor- tant command-line switches.

-public

Causes only public classes, members, and methods to be documented. You might want this for end-user documentation of a library.



image


Figure 5.1 Javadoc documentation viewed in Konqueror Web browser


-protected

Causes public and protected classes, members, and methods to be docu- mented. This is the default documentation level. This is also the most likely level at which you would want to document code meant for distribution.

-package

We suspect you can see where this is going. This switch causes package, protected, and public classes, members, and methods to be documented.

-private

This switch causes all classes, members, and methods to be documented. In our experience, this is the setting you will want to use for internal projects. It documents everything.

-sourcepath and -classpath

These are the paths that will be searched for source classes or referenced classes. These switches work like the corresponding switches for the javac compiler.


-verbose and -quiet

These switches control how much output is produced as javadoc runs. If you choose -verbose, detailed information is produced (more than the default; in current versions, this option mostly shows time measurements of the parsing of each source file). If you choose the -quiet option, progress messages are suppressed completely.

-doclet starting_class

We’re not going to go into too much detail on this, but this switch allows you to name a doclet (a class that uses the Doclet API) to use in place of the default doclet. See the next paragraph for more information.

All of the switches documented so far are provided by the javadoc program itself. Javadoc, like the rest of the Sun Microsystems Java SDK, is written in Java. The authors of javadoc took advantage of this. The default behavior of javadoc is to produce HTML documentation with a standard look and feel. However, there exists an API, called the Doclet API, which allows you to write a Java class of your own to process the information parsed out of the source by javadoc. For details, see the Doclet Overview3 on Sun’s Web site.

Sun provides a default doclet that produces HTML documentation. That doclet takes a number of command-line options as well. We’ll cover the most important of those now. Remember, these are provided by the standard doclet. If you use the -doclet switch, then these switches will not be available (unless, of course, the alternate doclet just happens to provide them).

-d directory

By default, the HTML documentation is saved in the same directory as the source. Use this switch to specify an alternate directory into which documentation is to be placed.

-use

Causes javadoc to generate a “Use” page for each class and package. Such a page is a cross-reference to all uses of the class or package.

-version

Causes any @version tag data to be included in the documentation. If you are using CVS for source control (and why wouldn’t you?) we



image

3. http://java.sun.com/j2se/1.4.1/docs/tooldocs/javadoc/overview.php


recommend adding $Id$ after the version tag, which CVS will automati- cally replace by its ID string containing the filename, CVS revision num- ber, date/time and the author of last check-in. (For more about CVS, see Chapter 8.)

-author

Causes any @author tag data to be included in the documentation.

-splitindex

Causes the alphabetical index to be broken into multiple pages, one per letter. Can be useful when you have a very large number of classes and/or packages documented in a single Javadoc document set.

-windowtitle title

Sets the title for the document set. The text that follows this switch will go into the HTML <title> element on documentation pages.

-nodeprecated

This causes all deprecated methods and classes to go undocumented. Normally they are documented, but marked as deprecated.

-nodeprecatedlist

Drops deprecated classes and methods from indexes, lists, and cross- references, but leaves the actual documentation in place.

There are actually many more switches. Some of the most important that we haven’t covered are the -link, -linkoffline, and related tags. If you end up producing many API packages and document them separately, you can use these switches to link your separate Javadoc documentation together seamlessly, so that when you use classes from separately documented packages, the refer- ences in the documentation for your code will be live links to that separate documentation. For details on these and other switches, see the Sun documentation on javadoc.4


image

4. http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.php