Customizing the Javadoc Tool

C1. How can I modify the standard doclet to produce links to source code from the API documentation?

NOTE - Javadoc 1.4 solves this problem with the -linksource option that provides links to HTML versions of the source code.

NOTE - The following example was written for Javadoc 1.2. The standard doclet code has changed enough in 1.3 to make this example not work. If anyone has updated this example for 1.3 and would like to publish those changes, please notify us and we will post it here.

Let's say you want to change how the standard doclet works, such as adding a custom tag or modifying its generated HTML output. If possible, your first approach should be to subclass the standard doclet. By not changing any of the classes in the standard doclet, this provides an easier upgrade path when we release a new version of the standard doclet. However, sometimes it is not possible to get the behavior you want merely by subclassing -- in that case you would need to copy the standard doclet and modify its classes directly. It would be wise to rename the starting class for this doclet from Standard to something else, since it would no longer have the standard behavior. In either case, it would help to look at the examples we have for writing a custom doclet in the Doclet Overview.
The standard doclet source files are located in the com.sun.tools.doclets.standard package of the standard doclet. Then use the -doclet option to run the new doclet.

The steps involved are as follows:

Copy the source code files for the com.sun.tools.doclets.standard package into a working directory from Sun's standard doclet source code. You don't need to copy files from the com.sun.tools.doclets package.

Remove the package declaration statement at the top of each source file in the copy. The package declaration statement looks like this:
package com.sun.tools.doclets.standard;
This step is necessary so that the Javadoc tool can distinguish the classes in your modified doclet from those in the real com.sun.tools.doclets.standard package.

You'll need to add or change a small amount code in these five source-code files: Standard.java
ClassWriter.java
HtmlStandardWriter.java
PackageWriter.java
PackageIndexWriter.java


These links take you to source-code files that have already been modified. Search these files for lines containing the comment '//new' to see what code has been added or changed.

Compile the source code files. Note that even though the modified files of the doclet are no longer in the com.sun.tools.doclets.standard package, they still import the other package of the standard doclet, com.sun.tools.doclets and, of course, the doclet API in package com.sun.javadoc. The class files for these two imported packages are in the lib/tools.jar file of the Java 2 SDK software, so be sure to use the -classpath option of the javac command to put tools.jar on the class path when you compile.

When the compilation is finished, you're ready to launch the doclet by using the command
javadoc -doclet Standard -sourcepath ...
We could also have changed the name of the entry-class for the doclet to something other than Standard to underscore the fact that the doclet is no longer really the standard doclet. If you do this, make sure to change the name Standard where ever it appears in throughout the other files of the doclet.

This doclet gets the location of the source code from the -sourcepath command-line option. It places a "Source Code" subheading and a link to the underlying source code and near the top of each class-level API file. The link is a "file:" link, not an "http:" link and is absolute rather than relative. See this sample HTML output.


NOTE: For purposes of this demonstration, to make the links work from your browser, we hand-modified the URLs in the sample output from the file: form. The original URL for the link to the Applet.java source file, for example, was:



If you want javadoc to be able to point to source files that aren't at the location specified by the -sourcepath option, you can use the doclet API to invent a new command-line flag for telling Javadoc where the source files are located. You would do this if you want to distribute your documentation and source files to someone else, say, for customers to download from your website.

C2. How can I change the colors and font sizes?

The old gray background was a little easier on the eyes, and I don't like the new font sizes.

Starting with 1.2, Javadoc supports HTML style sheets. You can change the background color back to gray with two simple changes to one file, stylesheet.css (located at the root directory of the Javadoc HTML files):
To change the page background color, change this:

body { background-color: #FFFFFF }
To:
body { background-color: Silver }

To change the cell background color to silver, for example, change this:

#TableRowColor { background: #FFFFFF } /* White */
To:
#TableRowColor { background: Silver } /* Silver */

(In 1.2 beta releases prior to the final JDK 1.2 release, the previous statment starts with a period ".TableRowColor" rather than a hash symbol.)

To choose a smaller, sans-serif fonts for the left-hand frames, change this:

#FrameItemFont { font-size: normal; font-family: normal }
To:
#FrameItemFont { font-size: 10pt; font-family: helvetica arial sans-serif }

(In 1.2 beta releases prior to the final JDK 1.2 release, the previous statment starts with a period ".FrameItemFont" rather than a hash symbol.)

If you find better values for a smaller font size for the left-hand frames, please let us know so we can publish them. For more information, see: What's New in Javadoc 1.2.

C3. How can I eliminate the HTML frames in the javadoc look?

Frames are entirely optional. If you don't want frames, don't use them. Simply turn frames off with a single click ("No Frames" near the top of any page). Or load the non-frame front page (overview-summary.html) instead of the frame set (index.html). All the navigation (except "All Classes") is available at the top of each web page. When you need to bookmark a page, you can always switch frames off with a single click and then switch them back on (although turning frames on always takes you to the front page).

C4. How do I document Java platform classes using a later version of Javadoc?

This issue is a special case, of interest only to those documenting one verion of the Java platform classes, say 1.1, with a later "dot" version of Javadoc, say 1.2. This is normally of interest only to Sun employees, but is also of interest to those who want to know in detail how Javadoc searches for classes.
When running Javadoc 1.2 and attempting to document 1.1 core packages, Javadoc will (perhaps surprisingly) also document the 1.2 classes in those packages. The reason this happens is because (1) Javadoc is documenting these classes based on information extracted from their .class files (not source files), and (2) Javadoc has a default -bootclasspath where that points to rt.jar that contains these class files.

The workaround is to unset -bootclasspath, by setting its argument to the empty string. When you ask Javadoc to document the java.lang package, for example, it will document all classes in that package that are found in the bootclasspath, even if the source files for those classes are not present. Since all the 1.2 classes are present in bootclasspath, it documents all those classes. This is not a problem when documenting non-core packages, because those classes do not exist on bootclasspath. For more information on bootclasspath, see Finding Classes.

For example, if you run Javadoc 1.2 on the java.lang package for 1.1, it will also generate a page for java.lang.Character.Subset which is present only in 1.2.

The solution is to unset bootclasspath and point sourcepath to the 1.1 source files. Pointing -sourcepath to the source files ensures that Javadoc can find everything referenced by the classes being documented.

% javadoc -bootclasspath "" -sourcepath [path_to_1.1_sources] java.lang
The double quotes are needed to tell the shell that the argument is empty. Here's an example with the real path for JDK 1.1.7:
% javadoc -bootclasspath "" -sourcepath
/java/jdk/1.1.7/ws/MASTER/src/share/java:/java/jdk/1.1.7/ws/MASTER/src/share/sun
java.lang
Note that the "sun" directory is included to prevent a slew of errors, since it is referenced. Using -sourcepath rather than -bootclasspath is also slower and uses more memory since all these referenced classes must be parsed.

C5. How do I workaround the new restriction in 1.4 that HTML tags cannot be used around parameter names?

Prior to 1.4, the Javadoc tool support HTML around parameter names in a method comment: /**
* @param values the value to get
*/
public void setValue(int value) {
}


Now that the standard doclet supports taglets, if a user wants all parameter names to be italic or bold, in the long run it would make more sense for them to write a taglet to do that, as it eliminates having to type HTML tags for every parameter. The the above comment would look like: /**
* @param values the value to get
*/
public void setValue(int value) {
}


However, if users don't want to change existing source code, they can use this ParamTaglet which allows the use of HTML around parameter names. Put the compiled class in a directory named /com/sun/tools/doclets/standard/tags and then use these options to javadoc:
-tagletpath
-taglet com.sun.tools.doclets.standard.tags.ParamTaglet
This taglet will override the built-in ParamTaglet.