Java

Javadoc Tips

FAQ
Frequently Asked Questions

Last modified: Thu Oct 12 20:23:50 PDT 2000

Javadoc Home Page
A. General Questions
A1. Where can I find the Javadoc tool and its documentation?
A2. How do I run Javadoc? How do I write Javadoc tags and documentation comments?
A3. How do I run Javadoc from within a Java application?
A4. How can I tell which version of Javadoc I'm running?
A5. How do I write a shell script or batch file to run Javadoc?
A6. Is there an easy way to print the many pages generated from Javadoc?
A7. Can I incrementally build a document from different runs of Javadoc?
A8. I'm using -link or -linkoffline but some of my external links do not show up. Why is this?
A9. Is there a way to redirect links between multiple independently-built HTML Javadoc trees?
A10. Where can I find the com.sun.javadoc and com.sun.tools.doclets packages?
A11. How does your implementation of Javadoc work?
A12. Can I run javadoc on source files from other languages, such as C, C++ or VisualBasic?
A13. I'd like to create custom tags, for example to mark methods to prevent them from being documented.
A14. Where can I find code examples for the JavaTM API?
A15. How can I exclude certain public members or classes from being documented?
A16. Where can I find the source code for the Javadoc tool and standard doclet?
A17. How would I create a makefile for documenting arbitrarily large libraries?
A18. May I see the slides presented at the JavaOne 99 Javadoc Birds-of-a-Feather session?
 
B. General Troubleshooting: Bugs, Errors and Warnings
B1. What bugs are in Javadoc?
B2. How do I redirect error messages to a file?
B3. I just can't get Javadoc to work over my entire source code; what do you suggest?
B4. I run out of memory -- how much is needed, exactly how do you call Javadoc, and how long does it take?
B5. Why aren't the memory flags (-J-m) recognized in Windows?
B6. When I run Javadoc on my source package, some links are not generated.
B7. In Javadoc 1.2.2, when using @see or {@link} tags to external classes, the links to methods, fields and constructors are missing.
B8. Why do I get the warning "Class or Package not found in @see tag"?
B9. The class comments are missing from the generated docs, but are in the source code.
B10. When I run Javadoc, I get the following exception warning: "Method X declares that it throws class Y, but there is no corresponding @exception item." What does this message mean?
B11. I copied all of my .java files from their package hierarchy into a single directory so it would be easier to run Javadoc on them, but it doesn't work.
B12. I am documenting 33 packages and added a new package to my javadoc command but this created a "No source files" error.
B13. I get the error "Class xxx already defined".
B14. I get the errors "FileNotFoundException" and "Fatal Exception".
 
C. Javadoc 1.2 and 1.3 Only
C1. I'm planning to upgrade from Javadoc 1.1 to 1.2 or 1.3 and am wondering what kinds of problems I might encounter?
C2. How can I modify the standard doclet to produce links to source code from the API documentation?
C3. How can I change the colors and font sizes?
C4. Please give us the old javadoc look back. The new look is much harder to navigate. NO FRAMES!!!
C5. Why do I get so many @serial warnings, including warnings about private fields?
C6. How do I document f Java platform classes using a later version of Javadoc?
 
D. Javadoc 1.1 Only
D1. Where can I get the .gif images that Javadoc 1.1.x output uses?
D2. Is there a way for Javadoc 1.1.x to include the necessary .gif files with its output?
D3. Is there any way for Javadoc 1.1.x to insert a heading or footer?
D4. How did you get Javadoc 1.1.x to break up the large (1.4 MB) index file into separate files A-Z?
D5. It seems that Javadoc 1.1.x does not work for documenting inner classes.
D6. When I run Javadoc 1.1.x, the index file (AllNames.html) that it generates is empty.
D7. When I run Javadoc 1.1.x with the -private option, the private members are not generated.
D8. Running Javadoc 1.1.x without -sourcepath gets "Warning: No source files for package xxx".
D9. Not all forms of the @see tag in Javadoc 1.1 work as documented.
 
E. Doclets
      Doclets from Sun Microsystems

      Doclets from Third Parties
 
F. Javadoc Tools and Custom Tags
Please send comments and suggestions to Javadoc Tool Email. We will update this FAQ page periodically to address the common problems that users of the Javadoc tool run into. Thanks to the many developers who have contributed.

General Questions

A1.  Where can I find the Javadoc tool and its documentation?

Javadoc tool - Included in the JavaTM development kits. You can obtain the Javadoc tool by downloading the relevant JDK or SDK -- this is the only way to obtain the Javadoc tool:

The javadoc executable is in the bin directory.

Javadoc Tool Documentation - This documentation is contained in the Java 2 SDK Documentation, which you can browse here or download separately. The "Javadoc Tool Reference Doc" mentioned below is the central reference to the Javadoc tool and is similar to Unix "man pages". It describes how to set up and run the Javadoc tool, with examples, and contains a reference guide to the tags and options.

Javadoc 1.3: Browse Javadoc 1.3 Tool Docs   Download as part of
Java 2 SDK v1.3 docs
    Shortcut to Javadoc Tool Reference Doc (Solaris)
Shortcut to Javadoc Tool Reference Doc (Windows)
 
Javadoc 1.2: Browse Javadoc 1.2 Tool Docs   Download as part of
Java 2 SDK v1.2 docs
     Shortcut to Javadoc Tool Reference Doc (Solaris)
Shortcut to Javadoc Tool Reference Doc (Windows)
 
Javadoc 1.1: Javadoc Tool Reference Doc (Solaris)
Javadoc Tool Reference Doc (Windows) 		  (Single web page --
just use "Save As" to download)

Javadoc Tool Home Page has links to all documentation and related information on the Javadoc tool, including proposed Javadoc tags.

A2.  How do I run Javadoc? How do I write Javadoc tags and documentation comments?

There are two ways to run Javadoc -- on classes and on packages. See the examples at the end of the Javadoc reference pages (listed above) for descriptions. Javadoc 1.1 has some important bugs, so if using that version, it is imperative to read the rest of this FAQ. Also, Javadoc uses parts of the Java Compiler (javac) to parse through the source code. It is therefore simplest if you run Javadoc on the same .java source files you used in your normal compile.

Once you've run Javadoc and want to view the generated HTML, the topmost page is named packages.html (in Javadoc 1.1) or index.html (in Javadoc 1.2 and later). This FAQ also tells you where to get the required GIF files required for Javadoc 1.1.

To get details on how to write Javadoc tags and documentation comments, this is the best place to start:

If your doc comments comprise an API specification, you might find this document useful:

A3.  How do I run Javadoc from within a Java application?

For Javadoc 1.2 and later: 
your_method() {
  
        // your code
        String[] javadocargs = { "-sourcepath",
                                 "/home/atuld/JDK/1.3/src/share/classes",
                                 "-nodeprecated",
                                 "-d",
                                 "applet",
                                 "java.applet" };
        com.sun.tools.javadoc.Main.main(javadocargs);
        // your code
}
The disadvantages of this are: (1) It can only be called once per run (since static information is stored) - use java.lang.Runtime.exec("javadoc ...") if more than one call is needed. (2) Exit code is not returned, so you can't tell if it failed. (3) Can't set where output goes or what the command is called.

For Javadoc 1.1.x, drop com (above) and instead use sun.tools.javadoc.Main.main(javadocargs);.

In the next major verion of Javadoc after 1.3 (probably to be called 1.4), we will be releasing a programmable interface for this in the form of an execute method. See Request 4113483.

A4.  How can I tell which version of Javadoc I'm running?

Javadoc does not actually have a version number contained anywhere in its executable or classes (tools.jar). By convention, we use the same version number for Javadoc as the JDK or SDK is it located in. Therefore, Java 2 SDK v1.2.2 contains Javadoc version 1.2.2.

To find the Javadoc version, simply find the version of the java executable by executing "javadoc -J-version".

Javadoc 1.2.2 gives this result: 

   C:\> javadoc -J-version
   java version "1.2.2"
   Classic VM (build JDK-1.2.2-W, green threads, sunwjit)
The letter "W" is the internal build letter.

Javadoc 1.2 gives this result: 

   C:\> javadoc -J-version
   java version "1.2"
   Classic VM (build JDK-1.2-V, green threads, sunwjit)

Javadoc 1.1.8 gives something like this result: 

   C:\> javadoc -J-version
   java version "1.1.8"
To get the actual build letter for 1.1, use "-J-fullversion": 
   C:\> javadoc -J-fullversion
   java full version "JDK1.1.8M"

A5.  How do I write a shell script or batch file to run Javadoc?

Typing a javadoc command on the command line is burdensome and error-prone, especially if you use many options. You can move part of the command into files in two different ways:
NOTE - On Solaris, it is very important to make sure the backslash continuation character (\) is the last character on any line, not followed by spaces. If it is followed by a space, javadoc will stop execution and display a misleading error message saying "No package, class, or source file found named ." and will implicate the next option on the command line. For example, in the example shell script above, if a space appears at the end of "-d docs \ ", then javadoc will not execute the next option -use. This would be the error message: 
   % run-javadoc-SOLARIS
   javadoc: No package, class, or source file found named  .
   1 error
   run-javadoc-SOLARIS: -use: execute permission denied
A6.   Is there an easy way to print the many pages generated from Javadoc? Sun currently provides the API docs only in HTML, which is not easily printable.
If you have the source code (containing the doc comments), and FrameMaker, and are willing to re-generate the documentation, you can use the MIF Doclet to convert to Postscript and print directly to a printer (or to PDF) with a single command.

Otherwise, the easiest way to print the documentation that we have found is to convert the documentation to PostScript using html2ps and then print that. (If you know of a good way of printing many HTML pages, please let us know.)

Jan Kärrman has written a freely available program html2ps which batch-converts files to PostScript for easy printing or conversion to PDF. We have used it only on Solaris. It is fast and works great. If you find that it works on Windows, please let us know. The earlier versions use alternate text rather than printing images.

Setup
html2ps converts HTML files to PS for easy printing. The URL for downloading html2ps from the author is: 
        http://www.tdb.uu.se/~jan/html2ps.html
This directory contains the html2ps program, a readme file and a man page.
Running html2ps on HTML files generated from Javadoc 1.2
Since the HTML files are in different directories, you must include the package names on the command line, or concatenate the HTML files together before running html2ps. For the java.applet package, you would cd to the root api docs directory and run: 
% html2ps *.html java/applet/*.html java/applet/class-use/*.html index-files/*.html 
          > apidocs.ps
Running html2ps on HTML files generated from Javadoc 1.1
Since the HTML files are all in one directory, you can run a simple command: 
% html2ps *.html > apidocs.ps
However, this causes classes to be printed one right after another, rather than having classes begin at the top of each page.
Notes
Page Order - If the above steps don't give you the pages in the order you want:
  1. At the beginning of each HTML file put an HTML comment: <!--NewPage-->
    (not necessary for Javadoc 1.2, since it automatically does this for you).
  2. Concatenate the HTML files together in the order you want them printed.
  3. Run html2ps on the huge concatenated file.
The <!--NewPage--> comment ensures that each new HTML page will begin on a new physical page when printed. Scripts that performs steps 1 and 2 have been written by Francine Le Peintre, Gerard Sookahet and Xavier Outhier, and are available at:

GIF Images - While html2ps does not handle GIFs, it does the next best thing, by substituting the alternate text for the GIF. Thus, it works great on the Java API generated from javadoc, which contains alternate text for its heading and bullet images.

No Navigation Bar - If you don't want the navigation bar to appear at the top and bottom of each page, use the -nonavbar option when running javadoc.

About html2ps
Author: Jan Kärrman
Dept. of Scientific Computing, Uppsala University, Sweden
e-mail: jan@tdb.uu.se

html2ps is a Perl script that is freely available. It works great and the author Jan is very responsive. html2ps supports a number of options.

A7.  Can I incrementally build a document from different runs of Javadoc?

Basically no, but there is a link feature that may provide what you need. First of all, Javadoc generates one and only one document each time you run it. It cannot modify or directly incorporate results from previous runs of Javadoc. However, it can link to results from previous runs. Here are these two cases:

A8. I'm using -link or -linkoffline but some of my external links do not show up. Why is this?

First ensure that the arguments to -link or -linkoffline are correct, and check that the package-list file exists at the location you expect it. You can check the latter by viewing it in a browser -- for example, the package list for the Java 2 Platform, Standard Edition, v1.3 API Specification is at: package-list.

If the above does not apply, it is still possible for a link to not appear due to a bug in Javadoc. For a link to an external referenced class to actually appear, the class must be referenced in a particular way -- it is not sufficient for it to be referenced in the body of a method or an automatic import statement. It must be referenced explicitly by name in either an import statement or a declaration. The most common workaround is described below.

If you are using Javadoc 1.2.2, if the above does not apply, and if @see and {@link} links are broken, then check with a -link bug in Javadoc 1.2.2.

WORKAROUND - The most innocuous workaround is to import the class explicitly, by name: 

   import java.lang.SecurityManager; // workaround to force @see/@link hyperlink
An automatic, or wildcard, import statement (such as import java.io.*) will not work. We strongly recommmend you add a comment similar to the one shown above to the right of the import statement, so the import statement can be removed once the Javadoc bug is fixed (it might not be fixed until after version 1.4).

This limitation is further described at How a Class Must Be Referenced for a Link to Appear

A9. Is there a way to redirect links between multiple independently-built HTML Javadoc trees after installing them from independent products into arbitrary locations?

Let's state the question a different way. Let's say a user downloads the JDK and its javadoc-generated API documentation (set A). Next, the user downloads and installs a third-party product with its Javadoc-generated API documentation (set B) in a user-defined location. They would like the references from set B to point to set A.

Currently, Javadoc can create links from set B to set A (using "Linking Documents" in the previous question) but they must be specified at Javadoc build time, and can only be either absolute (using http:// or file:/) or relative, but can't use an environment variable that the user sets to redirect the links.

This limitation is inherent in HTML, which does not allow environment variables in links. Some possible solutions or workarounds that we are aware of are:

Someday when browser source is XML rather than HTML, dynamic redirects may be possible.

A10. Where can I find the com.sun.javadoc and com.sun.tools.doclets packages?

The class files are contained in lib/tools.jar of the Java 2 SDK, Standard Edition that you download. To see its location in the SDK, look at:

Java 2 SDK File Structure

For Javadoc 1.1, the Javadoc classes were located in packages sun.tools.javadoc in classes.zip (doclets did not exist in 1.1).

A11.   How does your implementation of Javadoc work?
Javadoc requires and relies on the java compiler to do its job. The first thing it does is call part of javac to compile the code, keeping the declarations and doc comments but discarding the implementation. It builds a parse tree and then generates the HTML from that.

In fact, javadoc will run on .java source files that are purely stub files with no method bodies. This means you can run Javadoc in the earliest stages of design, while you are writing the API but have not yet implemented it. Stub files are also a possible format for translating doc comments into other natural languages (French, German, Japanese, etc.).

Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation. For example, the compiler creates default versions of constructors that are not present in the source code. If Javadoc did not use the Java compiler, it would be difficult to handle these special cases.

A12.   Can I run javadoc on source files from other languages, such as C, C++ or VisualBasic?
No. Javadoc runs only on Java source code. See the previous question for the explanation. However, other vendors have worked on such documentation tools. They are listed at the bottom of this page.
A13.   I'd like to create custom tags, for example to mark methods to prevent them from being documented.
To do this, it will take some creative programming on your part, as Javadoc does not yet have any facility to easily add custom tags. You can start by looking at the example at How can I modify the standard doclet. If you are willing to do this, and would like to make it available to others, please let us know.

We have published a list of proposed tags. In this list you will notice a proposed tag @exclude for preventing parts of API from being documented. We have not developed a doclet containing such a tag (although the next version of our MIF doclet provides a way of excluding classes). We will publish doclets on this website that we have created or that others have created and want published.

One developer has created a custom tag @inverse to keep tracks of bi-directional links in the Java code generated by a CASE tool. For instance: 

class Owner {
   /**
    * my dogs
    * @inverse myOwner
    */
   Dog[] dogs;
}

class Dog {
   /**
    * my master
    * @inverse dogs
    */
   Owner myOwner;
}
The @inverse tag will allow the UML CASE tool to reverse the two fields 'dogs' and 'myOwner' as only one UML association instead of two, which is the default when no information is provided about the coupling between the two fields. (Didier Simoneau)
A14.   Where can I find code examples for the Java API?
While we do not include many code examples in the Java API documentation, we do currently provide thousands of examples separately, for virtually all Java 1.1 API -- practically every class, interface, method, field and constructor -- from The Java Class Libraries: An Annotated Reference, by Patrick Chan and Rosanna Lee. While this book is not on-line, its examples are available for download at:

We also provide examples in the Java Tutorial, which is a programmer's guide to Java.

The earlier version Java 1.0 examples are also available at Java 1.0 code examples for java.applet, java.lang, java.util, java.io, java.net and java.awt

A15.   How can I exclude certain public members or classes from being documented?
Often you need to make a method public so that it can be accessible from other packages, not because you want it to be part of the public API. Having these methods appear in the documentation merely confuses application developers.

There is currently no way to hide, exclude or suppress public members from the javadoc-generated documentation.

If you want to exclude public classes or interfaces, you cannot do so when specifying package names on the command line. The only option is to pass into javadoc the source filenames for all classes you want to document, excluding those you don't want (which we realize is quite inconvenient). (You can put the list of classes in a command line argument file rather than directly on the command line.)

While knowledge of these public members is not needed by application developers, it is needed by re-implementors of the code. Since the API specs for the Java platform that Sun publishes are meant to be complete enough for re-implementors, the Java platform API specification does not have the need to suppress documentation for public members.

The way we handle members like these is to add a sentence to the doc comment saying this member is called internally and applications should not call them.

We are considering @exclude as a proposed tag for excluding members.

A16.  Where can I find the source code for the Javadoc tool and standard doclet?
The source code for the Javadoc tool (including the standard doclet) is contained in the source code for the Java software development kit, available at:

The standard doclet source code can be downloaded separately as part of:

A17.   How would I create a makefile for documenting arbitrarily large libraries?
One of our developers, John Visosky, has donated a generic batch file and makefile for running javadoc on Windows. Please see Javadoc'ing Large Java Libraries.
A18.  May I see the slides presented at the JavaOne 99 Javadoc Birds-of-a-Feather session?
  • JavaOne '99 Slides - Javadoc Tool and Doclets - Once at the first page, click on the Java coffee cup logo to go forward to the next slide, click at the top of the left-hand purple vertical stripe to go backward, and click in between those two spots to start over. (There are 6 miscellaneous slides after "The End".)

    • General Troubleshooting: Bugs, Errors and Warnings

    B1.   What bugs are in Javadoc?
    The most commonly encountered bugs are listed in this FAQ, along with workarounds where possible. In addition, each release of the Java 2 SDK includes a list of changes to the Javadoc tool, which lists some of the important bugs fixed in that particular release; see What's New in Javadoc 1.3, 1.2.2 and 1.2.

    You can also see Javadoc bugs (or any Java bugs) at Java Developer Connection (JDC), which anyone can join for free. Go to JDC and click on "Search" at the top of any page. Then choose "Only search bugs" and type "javadoc".

    B2.   How do I redirect error messages to a file?
    On both Solaris and Windows NT, you can redirect the standard message stream by using the ">" operator, and redirect the error messages stream by using the "2>" operator. For example, on NT, to redirect the standard messages to log.std and the error messages to log.err: 
       C:> javadoc -d docs java.lang >log.std 2>log.err
    You may find it much more useful to redirect both streams to the same file, then search through the log file for the string "warning." (This is because for Javadoc 1.3 and earlier, the filename being processes appears in the standard output rather than the error output.) The following example works on Solaris and Windows NT 4.0: 
       C:> javadoc -d docs java.lang >javadoc.log 2>&1
    B3.   I just can't get Javadoc to work on my entire source code; what do you suggest?
    Here are some ideas. Basically, start small and work up:
    B4.   I run out of memory -- how much is needed, exactly how do you at Java Software call Javadoc, and how long does it take?
    Javadoc does take a lot of memory because (unlike javac) it must simultaneously load all the classes being documented, plus any that are referenced (such as superclasses and superinterfaces). Javadoc 1.1.x uses 40 MB of memory to generate the JDK 1.1.x documentation (22 packages). Javadoc 1.2 requires 120 MB of memory to generate the JDK 1.2 documentation (55 packages), which takes 8 minutes on an Ultra Enterprise with 512 MB of memory. Generating docs for all our public classes including sun.* (129 packages) requires 200 MB and takes 15 minutes on that same machine.

    The javadoc 1.1.x command is shown with the -J-mx40m option below. Also, there is a bug in JDK 1.1.2 (fixed in 1.2), where the "ms" value must be smaller than (not equal to) the "mx" value. Without showing the complexity of environment variables and paths, the following is effectively the command that we run on the JDK 1.1 source code: 

    javadoc -J-ms39m -J-mx40m \
             -classpath /usr/latest/build/solaris/classes \
	     -d /usr/latest/build/doc/api \
	     -sourcepath /usr/latest/src/share/classes:/tmp/javadoc \
             java.io java.lang java.lang.reflect java.util java.util.zip \
	     java.awt java.awt.datatransfer java.awt.event \
	     java.awt.image java.net java.applet \
	     java.sql java.rmi java.rmi.registry java.rmi.server \
	     java.security java.security.acl sun.tools.debug \
	     java.text java.math java.beans \
	     java.rmi.dgc java.security.interfaces
    Fortunately, there are easier ways to run Javadoc without using the -classpath and -sourcepath options. See the Javadoc reference page.

    For javadoc 1.2, this is the command we run (in a Solaris 'make' file) on the JDK 1.2 source code: 

    
javadoc     -J-Xms120m -J-Xmx120m               \
            -splitIndex                         \
            -title $(JAVADOCTITLE)              \
            -header $(JAVADOCHEADER)            \
            -footer $(JAVADOCHEADER)            \
            -bottom $(JAVADOCBOTTOM)            \
            -d docs/api                         \
            -sourcepath ../src/share/classes/   \
            $(COREPKGS)

JAVADOCTITLE  = 'Java<sup><font size="-2">TM</font></sup> Platform 1.2 Beta 4 API Specification'

JAVADOCHEADER = '<b>Java Platform 1.2</b><br><font size="-1">Beta 4</font>'

JAVADOCBOTTOM = '<font size="-1">Java is a trademark of Sun Microsystems,  Inc.</font>'

COREPKGS =  java.applet                   \
            java.awt                      \
            java.awt.color                \
            java.awt.datatransfer         \
            java.awt.dnd                  \
            java.awt.event                \
            java.awt.font                 \
            java.awt.geom                 \
              etc.
    For an example using a make file, please see the makefile question.
    B5.   Why aren't the memory flags (-J-m) recognized in Windows?
    In JDK 1.1.x, 1.2 Beta 1 and 1.2 Beta 2 on Microsoft Windows, there is a bug in the Javadoc wrapper that prevents the -J flags from being passed on to the virtual machine. The symptom is that when you specify the -J option, it says "invalid flag", as follows: 
      C:\> javadoc -J-mx40m MyClass.java
  javadoc: invalid flag: -J-mx40m
  usage: javadoc flags* [class | package]*
        -sourcepath   Colon-separated list of source-file directories
        -classpath    Synonym for -sourcepath
        ...
    WORKAROUND - Switch to Javadoc 1.2 Beta3 or later (you can use the -1.1 switch to make it look like the 1.1 javadoc output with gray background and GIF images for headers). Otherwise, bypass the wrapper script in JDK 1.1.x by running the Main class (which contains a "main" method) in the sun.tools.javadoc package, assuming the destination directory is "C:\html": 
      C:\> java -mx40m sun.tools.javadoc.Main -d html MyClass.java

    B6.   When I run javadoc on my source package, some of the links are not generated. For example, for methods that have parameters of type Object, those parameters have no link to documentation for the Object class.

    In Javadoc 1.2 and later, use the -link or -linkoffline options to create links to external referenced classes. These are classes outside of the packages passed in to the javadoc command. Therefore, if you run javadoc only on your own, it will not provide links to java.lang.Object unless you include one of these two options.

    Javadoc 1.1 does not have these options to generate links to external referenced classes. (Javadoc 1.0 does include links to classes outside of the packages being operated on, but that means those links would be potentially broken links.)

    See the next question for a related bug.

    WORKAROUND - Use the -link or -linkoffline options, or include the package or class in the javadoc command that you run.

    B7.   In Javadoc 1.2.2, when using @see or {@link} tags to external classes, the links to methods, fields and constructors are missing.

    I am calling javadoc with "-link http://java.sun.com/products/jdk/1.2/docs/api". If I link to a class in 1.2.2 it works, but not if I link to a member. With v1.3 both classes and members work! For example: 
           import javax.swing.tree.TreeModel;
  
       /**
        * This is an example with a link to the method 
        * {@link TreeModel#getChildCount(Object) getChildCount()}
        * and it doesn't work with JDK 1.2.2
        */

    This is a known bug only in 1.2.2. In 1.2.2, the -link and -linkoffline options link only to packages, classes and interfaces but not to members. This bug is not present in either earlier (1.2.0) or later (1.3.0) versions.

    WORKAROUND - Use Javadoc 1.2.0 or 1.3.0 (also known as versions 1.2 and 1.3). These are the versions found in the Java 2 SDK versions 1.2.0 and 1.3.0, respectively.

    B8.   Why do I get the warning "Class or Package not found in @see tag"?
    When @see or {@link} refers to a Java name that is not referenced -- that is, not used anywhere in the implementation of the classes being documented -- javadoc cannot find it, and displays this warning: 
    javadoc: warning - Class or Package not found, in @see tag: xxx
    The following source file Test.java generates a warning. 
    import javax.swing.*;

/**
 * @see JSplitPane
 */
public class Test {
}
    When you run javadoc, you get a warning: 
     % javadoc Test.java
 javadoc: warning - Class or Package not found, in @see tag: JSplitPane
    The follow generates the @see link properly, without warning: 
    import javax.swing.*;

/**
 * @see JSplitPane
 */
public class Test
{
   public JSplitPane p;
}

    WORKAROUND - Include a reference to the Java name you want to include, as shown in the example above.

    B9.   The class comments are missing from the generated docs, but are in the source code. I only get the doc comments for the methods, fields and constructors.

    If the class-level doc comments are missing, a common mistake is putting the import statement between the doc comment and the class definition in the source file. There must not be any statements between the class doc comment and the class declaration. 
        /**
     * This is the class comment for the class Whatever.
     */

    import com.sun;   // MISTAKE - Important not to put statements here

    public class Whatever {
    }
    SOLUTION - Move the import statement ahead of the class comment.
    B10.   When I run javadoc, I get the following exception warning: "Method X declares that it throws class Y, but there is no corresponding @exception item." What does this message mean?
    This warning message means that there is no description on the line that contains the @exception tag. The @exception line should look something like: 
       * @exception  ReceiverException  An exception thrown by the receiver.
    You get the warning if there is a return immediately after the exception name (ReceiverException). If you put the description on the next line, for example, you get this warning.

    WORKAROUND - Insert a space after the exception name.

    B11.   I copied all of my .java files from their package hierarchy into a single directory so it would be easier to run javadoc on them, but it doesn't work. I get the message "Couldn't find <classname>"?
    If your classes do not all belong to the unnamed package, you must put them in directories named after the packages. Do not put all .java files into the same directory (even if they will compile that way). For example, files belonging to java.awt and java.awt.swing must be in these directories: 
             DIRECTORIES 

           java
             |
             |
            awt
             | 
             +----------+
             |          |
           swing     *.java    (java.awt source files)
             | 
             +----------+
                        |
                    *.java     (java.awt.swing source files)
    It is normally not possible for javadoc to run successfully when classes from different packages are in the same directory, because of certain dependencies between classes. Also, it's worthy to note that because javadoc calls parts of the java compiler to parse through the source code, it will not run on source code that is not compilable.
    B12.   I am documenting 33 packages and added a new package to my javadoc command but this created a "No source files" error.
    There is a limit to the number of characters Windows allows on the command line, about 1000 characters. A hint is that the error message lists a package name that is truncated. If the last package name is "com.mypackage", the error message might look like: 
       Warning: No source files for package com.mypackaC:\project\src
    Notice the end of the line is corrupted: com.mypackaC:\project\src. This same problem can occur in Javadoc 1.1 or 1.2.

    WORKAROUND - In 1.2 or later you can use the argument file feature which allows arguments of any length to be placed in a file: 

      javadoc @args
    This is not implemented prior to 1.2 Beta4, so if using Javadoc 1.1, you must switch to Javadoc 1.2 or later, or run Javadoc on Solaris which has no such length limit (allows at least 10,000 characters).
    B13.   I get the error "Class xxx already defined".
    Problem #1 - This command:

    javadoc ca.mcgill.sable.sablecc ca.mcgill.sable.sablecc.lexer

    produced this error message: 

    Loading source files for package ca.mcgill.sable.sablecc...
Loading source files for package ca.mcgill.sable.sablecc.lexer...
.\ca\mcgill\sable\sablecc\lexer\Lexer.java:17: 
Class ca.mcgill.sable.sablecc.lexer.Lexer already defined 
in ca/mcgill/sable/sablecc/lexer/Lexer.java.
public final class Lexer
                   ^
.\ca\mcgill\sable\sablecc\lexer\LexerException.java:10: 
Class ca.mcgill.sable.sablecc.lexer.LexerException already defined 
in ca/mcgill/sable/sablecc/lexer/LexerException.java.
public class LexerException extends Exception
             ^
2 errors
    When running Javadoc on each package separately, it works ok. When combining them, Javadoc complains about every class in the second package. Am I doing something wrong, or can javadoc just not handle more than one package?

    Solution #1 -

    Your CLASSPATH includes both the jar file for the classes being documented and the un-jarred source files, so Javadoc thought there were duplicate definitions, but, oddly, only when you run Javadoc with more than one package name. The solution is to remove the jar file from the CLASSPATH. Note that you should be using SOURCEPATH to specify the path to the source files, anyway.

    Problem #2 -

    Someone else wrote in to say they get this error message "Class xxx already defined" when they comment out a class definition. If the whole class definition is commented, then error will be generated on class1, class2 and class3 (if they are already loaded by javadoc). 

    package some.package;

import some.class1;
import some.class2;
import some.class3;

/*
public class SupClass {

    public void method1() {}

}
*/
    Solution #2 -

    The solution is: Do not comment out the class definition.

    B14.   I get the errors "FileNotFoundException" and "Fatal Exception".
    Problem - A user encountered the above errors when he tried to build the Javadoc documentation for a package called config. (Solaris operating system, Javadoc 1.2.1) 
    % javadoc -d htm -sourcepath /home/project config

Loading source files for package config...
java.io.FileNotFoundException
        at sun.tools.javac.BatchEnvironment.parseFile(Compiled Code)
        at com.sun.tools.javadoc.Main.parseSourcePackage(Compiled Code)
        at com.sun.tools.javadoc.Main.initInner(Compiled Code)
        at com.sun.tools.javadoc.Main.init(Compiled Code)
        at com.sun.tools.javadoc.Main.main(Compiled Code)
javadoc: fatal exception
1 error
    One symptom was that when he ran javadoc in the directory config and built the documentation for all classes (rather than for the package), there was no error. 
     % cd config
 % javadoc -d ../htm -classpath /home/project *.java
    He didn't have a problem with any other package.

    Solution - After a lot of sleuthing, he found a (hidden) file called: 

        .#CreateConfig.java
    in the config directory. After removing this file, it worked.

    Moral of the Story - Look for stray .java source files that don't belong to the package.

    Javadoc 1.2 and 1.3 Only

    C1.   I'm planning to upgrade from Javadoc 1.1 to 1.2 and am wondering what kinds of problems I might encounter?
    Javadoc 1.2 has been through a much more rigorous design and testing program than 1.1, and has proven to be a much more reliable and robust tool. We have also been careful to write Javadoc 1.2 to be compatible with documentation comments written for previous versions of Javadoc. However, there may be a few cases where old documentation comments may not "work" the same when compiled with Javadoc 1.2. Please read the incompatibility section of What's New in Javadoc 1.2. Please let us know of any other incompatibilites you run across.
    C2.   How can I modify the standard doclet to produce links to source code from the API documentation?
    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:

    1. 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.

    2. 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.

    3. 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.

    4. 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.

    5. When the compilation is finished, you're ready to launch the doclet by using the command 
      javadoc -doclet Standard -sourcepath <path to source code files> ...

    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:
    <a href="file:/home/username/ws/JDK1.2/src/share/classes/java/applet/Applet.java">
    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.
    C3.   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.

    C4.   Please give us the old javadoc look back. The new look is much harder to navigate. NO FRAMES!!!
    Thank you for your comments.

    First, 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). 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).

    People are voting in favor of the new look about 4:1. In general, if you don't use frames and are already familiar with the API, there is more scrolling and more "clutter" due to the one-sentence summaries for the packages and classes. These one-sentence summaries are helpful for those who are not familiar with the API.

    The new look is easier to navigate than the old look if you use frames -- with very little scrolling you can jump directly to any package or class with one or two clicks. Frames are meant for the advanced users who want to avoid the one-sentence summaries.

    The method, constructor and field summaries now display "static" and the return type. We use tables so that the API names will align in a column. The old look did not show "static" or return values.

    In addition, we removed the old graphic headings because they were more difficult to translate.

    If you simply must have the old look, Javadoc will still generate it with the -1.1 option. Once we ship the full, non-commercial source release to JDK 1.2, you could run Javadoc on it.

    For more information on the new look, see: Changes to the Standard Doclet for Javadoc 1.2.

    C5.   Why do I get so many @serial warnings, including warnings about private fields (when I'm not using the -private options)?
    There is currently no way to turn off the @serial tag warnings. A future maintenance release will turn the warnings off by default and will only be enabled when you provide a command line option (such as -serialwarn) to javadoc. You can safely ignore the warnings but you cannot turn them off. We can only suggest filtering the warnings out for now.

    Any non-static and non-transient field of a Serializable class is considered a serializable field. Any field is serializable, regardless of its access type (public, private or protected). Thus, private Serializable fields require a javadoc comment that includes an @serial tag. Requiring the @serial tag to be added to a default serializable field's doc comment carries the requirement of adding this tag to private fields.

    For more information, see Why does the javadoc standard doclet generate many warnings about missing @serial and/or @serialData tags?, which also covers the question "Why do I see javadoc warnings stating that I am missing @serial tags for private fields if I am not running javadoc with the -private switch?". Also see @serial tag.

    C6.   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.

    Javadoc 1.1 Only

    D1.   Where can I get the .gif images that Javadoc 1.1.x output uses?
    Download the .gif images and "API users guide" file here (~24K). This latter file is named API_users_guide.html, which you access by clicking on the link "API User's Guide" in the upper left corner of the first page (packages.html). Please see the README. You can also obtain them from the docs/api/images/ directory in the downloadable JDK docs.

    D2.   Is there a way for Javadoc 1.1.x to include the necessary .gif files with its output?

    When I run javadoc, all the images (for headings and bullets) in the generated HTML files appear as broken links. Is there a way, other than manually copying the images, to get javadoc to include the necessary .gif files with its output?

    No. Currently, you must copy the .gif files separately from running javadoc.

    The .gif files reside in the api/images directory. To get the .gif files, download the JDK Documentation bundle and look in the docs/api/images directory. In your javadoc destination directory, create an images directory and copy the .gif files there.

    You can automate this process by writing a batch file (or shell script) that runs javadoc and also copies the images to the destination directory.

    Unnoticed by many people, when they do a javadoc build, there is another broken link "API User's Guide" in the upper-left corner of the packages.html page. This is a link to the file API_users_guide.html, which describes how the API docs are organized and includes the legend for the color-coded bullets. You must also copy this file over to the output destination.

    We have improved Javadoc 1.2 and later versions to no longer require graphics. We have renamed API_users_guide.html to help.html, and there is a command line option to omit the link to it from the navigation bar. If you include the link, you must manually copy the file to the destination.

    D3.   Is there any way for Javadoc 1.1.x to insert a heading or footer? I notice you have a header and footer on some of the API docs you publish.
    This capability has been added to Javadoc 1.2. In earlier versions of Javadoc, we added these headers and footers by running a script on the generated HTML files.
    D4.   How did you get Javadoc 1.1.x to break up the large (1.4 MB) index file into separate files A-Z, starting with a-index.html.
    Javadoc didn't do this. We did this with the PERL script javadocindexsplit.pl, which we ran on Solaris using Perl 5.0. Feel free to use it.

    Javadoc 1.1.x generates an index file "AllNames.html". This script does not modify the file "AllNames.html" itself, but copies its content into the files a-index.html, b-index.html, ..., y-index.html. (Unfortunately, javadoc 1.1.3 does not generate index entries for API names starting with "z". This is fixed in a later release.) To complete the job, you need to make the links that point to "AllNames.html" work instead with "a-index.html". The link "AllNames.html" appears at the top and bottom of most html pages, identified with the label "Index". You can do this in any of several ways:

    D5.   It seems that Javadoc 1.1 does not work for documenting inner classes.
    This has been fixed in Javadoc 1.2. This will not be fixed in any 1.1.x version of Javadoc.

    WORKAROUND - There is no known workaround.

    D6.   When I run javadoc, the index file (AllNames.html) that it generates is empty.
    This is a bug where javadoc appears to run successfully, but the index page is blank except for the header and title at the top of the file. This happens in two cases we have identified: WORKAROUND - Switch to Javadoc 1.2, which fixes this problem. This is fixed in the default 1.2 output and with the -1.1 option of Javadoc 1.2. The -1.1 option generates the 1.1 look with the 1.1 flat destination file structure.

    If you must use Javadoc 1.1.x, one poor "workaround" is to temporarily remove the keyword "public" or "protected" (so that javadoc won't try to document that member, but will generate the index without it) or remove the leading non-alphabetic character. We have no plans to fix this bug in future 1.1.x versions of Javadoc.

    D7.   When I run javadoc with the -private option, the private members are not generated.
    The -private, -protected and -package options were introduced in JDK 1.1.2. These options work properly on members of a public class, but unfortunately have never worked properly on members of non-public classes. Therefore, only comments for public classes and any of their members can be generated. Instead of generating the doc comments, it generates this message:
    This class is not public and therefore cannot be used outside this package.
    This bug has been fixed in Javadoc 1.2. This bug will not be fixed in any JDK 1.1.x version of javadoc.

    WORKAROUND - Switch to Javadoc 1.2. Otherwise, ugly though it may be, you can change all classes to "public" in the source code, generate the docs, and then selectively remove the word "public" from the generated docs. This last step requires selectively searching for: 

    "<dl>
  <dt> public "
    and replacing it with: 
    "<dl>
  <dt> "
    Brian Erwins has written a "fixpublic" script that runs on Solaris with Perl 5. This script both adds "public" to the source files and removes "public" from the proper places in the generated HTML files. This script has some Unix dependencies.
    D8.   Running javadoc without -sourcepath gets "Warning: No source files for package xxx".
    The javadoc reference page says under "Documenting One or More Packages" that you can run javadoc without -sourcepath. However, this doesn't work in JDK 1.1.x due to a bug in javadoc.

    WORKAROUND - Include the sourcepath option with a "dot" (.) for the current directory:

    javadoc -d html -sourcepath . java.awt
    D9.   Not all forms of the @see tag in Javadoc 1.1 work as documented.
    Using a URL in an @see tag does not work in Javadoc 1.1.x, but works in 1.2: 
          @see <a href="spec.html">Java Spec</a>
    In 1.1.x, it generates the error: "Extraneous text following reference."

    Other forms of the @see tag documented in the Java Language Specification also do not work in 1.1.x, though we have not enumerated them here. (Anyone who can add to this list, please let us know.)

    Doclets

    DISCLAIMER: We do not test, endorse or guarantee the utility or fitness of this software. Use at your own risk.

    Doclets From Sun Microsystems

    MIF Doclet Home Page contains information about the MIF Doclet. This doclet is being developed by the Javadoc team. It enables you to generate files that you can open in FrameMaker and save as Postscript, PDF, RTF, Word or WordPerfect documents. This is not a supported product -- we have developed it for internal use and have made it available as-is, with no warranty or promise to fix bugs.
    DocCheck is a doclet in the Sun Doc Check Utilities that checks doc comments in source files and generates a report listing the errors and irregularities it finds.
    We have translated the doc comments and API documentation into other languages, for example Japanese API docs (To view the Japanese characters, in Netscape, choose View > Character Set > Japanese (Auto-Detect).) Full translation involves translating both the doc comments and "labels". Labels are static text that includes headings, subheadings, the navigation bar, standard links, generic phrases, and help. Examples include the words "Overview", "Package", "Class", "Member Summary", "Subclasses", and "Methods inherited by". Full translation should also include translating any text or images in the doc-files directories, if any. If you have a need or interest in such a translation process, please contact us at docs@java.sun.com. We have no plans for releasing these doclets, but may do so on an experimental level if there is enough demand to do so.

    Doclets From Third Parties

    Dynamic Javadoc (called DJavadoc) generates API documentation that has dynamic hide/show capabilities. You can view the Java 2 Platform API Specifications now available for testing on the web. Please have a look and send any comments you may have to Erik Berglund. This version makes use of DHTML-features available in Internet Explorer 4 or later (Netscape 4 does not have enough of these DHTML features) to enable the reader to create more-focused or less-focused views of the documentation. In the current version the user may also create a more focused navigation view of the whole package-structure in a bookmark-like fashion.
    Nicolas Zin has published a simple RTF doclet for generating RTF from doc comments. You can download the RTF doclet. This works with Javadoc 1.2 or later. The generated files were tested to work with WinWord 97. A README.txt file in contained in the download bundle describes how to run it and welcomes bug fixes.
    TexiDoclet generates API documentation in TexInfo (.texi) or Info format (.info). It includes a context-sensitive documentation lookup system for the GNU Emacs editor.
    C2 Technologies, Inc. has created a LaTeX2e doclet to aid in the creation of printed documentation. Please send email to Gregg Wonderly
    iDoclet is an extension of the Javadoc 1.2 standard doclet that includes support for three new tags: 
       @pre
   @post
   @inv
    These tags are used by a Java preprocessor called iContract (mentioned below). iContract includes support for true design by contract, found in the Eiffel language. This is an advanced object-oriented assertion mechanism.

    Look here for Sample HTML documentation generated using iDoclet . The doclet is freeware programmed by Aslak Hellesøy.

    DocLint is a doclet that checks doc comments for missing comments and other documentation discrepancies.
    Java2Rose is a doclet that converts Java source files (*.java) to Rational Rose import files (*.red).
    EJBDoclet is a doclet, licensed as OpenSource, that allows you to generate various EJB files from a commented bean source file:

    Javadoc Tools and Custom Tags

    DISCLAIMER: We do not test, endorse or guarantee the utility or fitness of third-party software. Use at your own risk.
    Javadoc will not recurse over source directories for you. The following scripts are for developers who are documenting many packages and want javadoc to run on the source files in all subdirectories of a given "root" directory.

    Platform-Independent Recursion

    Here is a platform-independent solution to recurse directories, building a list of package names for javadoc. It works by recursing down through the directory names you pass in, looking for any directories that contain *.java filenames. In other words, it assumes a package is any directory that contains a .java file (which is not always a good assumption, obviously).

    1. Download the source file JavadocRecurse.java. Compile it: 
      C:> javac JavadocRecurse.java
    2. Build a file containing a listing of package names, where each rootdir is a directory where package directories are rooted: 
      C:> java JavadocRecurse packages.txt rootdir1 rootdir2 rootdirN

      For example, if your package is com.myCompany.myPackage, located at C:\source\com\myCompany\myPackage: 

      C:> java JavadocRecurse packages.txt C:\source

    3. Then use @packages.txt for your source packages: 
      C:> javadoc -d doc @packages.txt
    The above code was submitted by James Schriever (jamess@sterwent.com), Sterling Wentworth Corporation.

    The following is a solution for Solaris makefiles.

    Solaris Only
    The following script also builds a list of package names.

    1. In your 'make' file, build the list of package names with the statement:

      PACKAGES:sh = find subpackage -type d | sed "s,/,.,g"

      where subpackage is the top part of the package name, such as java from java.applet. For example,

      PACKAGES:sh = find java -type d | sed "s,/,.,g"

      would find all subdirectories as follows, and change the directory separators (/) to dots (.): 
      java
java/applet
java/applet/doc-files
java/lang
java/lang/reflect
      Notice it includes any "doc-files" directories, which you would need to filter out.

    2. Then run the javadoc statement in the makefile: 
      javadoc -d doc $(PACKAGES)
    This suggestion was submitted by Cal Cluff at Illgen Simulation Technologies, Inc.

    Windows Only

    The following works on Windows NT, but has the limitation that it generates a list of source files rather than package names. Because it does not process whole packages, it will not process the package.html files, nor will it generate lists of packages in the output. 

        for /r %1 in (*.java) do javadoc %1
    Doc+ is a full featured authoring and editing tool for Javadoc comments. Doc+ is to Javadoc what HTML editors are to web page design. It allows the developer to write Javadoc comments for classes, fields and methods present in the code. The developer can scan and work with multiple source files concurrently. The developer has the ability to quickly and easily create, remove and edit Javadoc tags. Doc+ provides a preview of the HTML that will be generated by Javadoc and a source code viewer. Advanced features such as autofill, templates, comment conversion, and a concept called PackageMaps make documenting a large project a matter of minutes. Custom tag feature ensures support for any new Javadoc tags. A bonus feature is integrated JavaHelp for quick reference. Developed by WoodenChair Software Corp. (Not to be confused with Doc++.)
    DocWiz allows you to easily add Javadoc comments to your source code, without tedious hand-formatting. It also protects you from editing the source code. When you open a Java source file in DocWiz, it provides a list of all the fields, methods and classes defined in that file. Click on any of these code elements to display an editable fill-in form containing the comments. After editing the comments, save the file to incorporate the changes into the file.
    2-Frame Interface with package/class/method access is a small set of files that change the interface to the API docs from 3 frames to 2 frames. The left-hand frame first shows a list of all package names; when you click on a package, the package list is replaced with all class names in that package; when you click on a class, the class list is replaced with all method names in that package. Very nice design. From Dave Hunter.
    API Search. Are you tired of browsing the Java API with Netscape's "Find..." ? Then this applet may be of assistance. Just type in a string and the applet tries to match it to all methods and variables in the Java API. The results are then displayed in a listbox. Clicking on an entry shows the documentation of the entry as generated by Javadoc.

    A word of warning: API Search offers several versions. Depending on the version you choose, the loading time may be well over one minute as a JAR file with the compiled index will be loaded.

    Infospheres Java Coding Standard. This is an elaborate extension to the standard set of tags. It includes the specification of preconditions, postconditions, class invariants, loop invariants and variants to generate test code with a parsing preprocessor. It includes a debugging package that provides assertions, debugging messages, logging, carrying distributed context, and so forth. Includes custom tags such as @history, @bug, @review, @todo, @concurrency, @precondition, @requires, @ensures, @generates, @modifies, @postcondition, @hides, @overrides, @equivalent and @example. Created by members of the Infospheres team at Caltech.
    Jindent is a source code formatting tool for the Java language. Jindent supports numerous options and switches to transform Java sources to your very own coding style including the Java Coding Style proposed by Sun. Furthermore, Jindent is able to generate javadoc templates.
    The Emacs editor (GNU Emacs, XEmacs) supports Sun's coding standard (such as indentation) for Java. Both versions of Emacs support this standard through the built-in use of the cc-mode package (also available separately at http://www.python.org/emacs/cc-mode).

    If you know of other editors, please let us know and we will add them to this list.

    iDoc is a free quality assurance (QA) tool for doc comments in Java source code. It supports developers in keeping source code doc comments up to date, in synch with the code itself and compliant with Java guidelines. iDoc analyzes the doc comments and code of classes, interfaces, methods and instance variables. iDoc is fully compatible with javadoc and complements it by providing several features that javadoc does not provide. (As of August 1999, it has not been updated for Javadoc 1.2.)
    iContract. Until now, the explicit specification of contracts by means of class invariants and message pre- and post-conditions was only available to Eiffel developers. iContract is a freely-available tool that provides the same thorough support for Java, enabling developers to take advantage of the following benefits: (a) supports design for testability by enhancing the systems observability (failure occurs close to fault), (b) uniform implementation of invariant-, pre- and post-condition-checks throughout your team, (c) documentation and code are always in synch and (d)semantic level specification of what requirements/benefits a class/message offers. (Also see design by contract in the JDC bug thread.)
    Here are a few -- if you know of others, please let us know so we can add them to this list.
    teikade is an environment to assist developers in writing programs using the Java language. The system includes a class browser and editor, hierarchy browser, a compilation frame, an execution frame, and tracing of references.
    idldoc is a program that accepts OMG IDL source code and writes HTML documentation for the contained definitions. It can be used to provide Web-accessible documentation for CORBA-compliant distributed objects. See the sample pages generated by idldoc. This program is completely unrelated to javadoc and doclets, except that the design of its source code documentation comments and generated HTML pages resemble that of javadoc.
    Swing interface to Javadoc 1.1 (click on "Download"). Must also install Swing for JDK 1.1 and AltaBeans. To see the interface, view the interface here. Send email to Stéphane Nicolas.
    The AutoRad system leverages the ability to write doclets for Javadoc 1.2, defining custom javadoc tags for GJT packages that specify the release of the package, the packages that the package depends on, as well as the release tags of those dependent packages.
    JVISION creates UML class diagrams from Java code or Java source to document existing Java applets and applications and for learning other people's code.

    The new JVISION Documentor beta adds a project and diagram manager integrated with Javadoc from Sun. Create an instant web site documenting an entire project. Navigate through a tree hierarchy of diagrams and click on a class to see Javadoc HTML.

    CommentMaster is a tool designed to help developers comment source code written in the Java language. It recursively reads files defined in a tree and formats comments to be compliant with the Javadoc standard. Users are able to define custom templates for missing comments. CommentMaster will comment files, classes, methods, variables, and inner classes. With an intuitive project wizard, it allows developers to fix comments in a matter of few minutes and work with multiple projects at the same time. Developed by Objectsoft, Inc

    Copyright © 1997-98 Sun Microsystems, Inc. All rights reserved.

    Please send questions that you would like added to this FAQ to:
    javadoc-tool@sun.com

    We publish some of the Javadoc feature requests at Bug Parade at the Java Developer Connection website. (Registration is free.) Search for "javadoc" or whatever you might want.

    If you are writing to the above email address to ask about problems running javadoc, you must provide the following information:

    • The version of javadoc (type "java -version", not "javadoc -version").
    • The exact javadoc command you are executing, with all options.
    • The fully-qualified name of the package or class you are trying to document
      (such as com.mycompany.testpackage or com.mycompany.testpackage.testclass.java).
    • The full path of the package(s) or class(es) you are running javadoc on. (If a class, include the .java filename). Such as C:\java\com\mycompany\testpackage or C:\java\com\mycompany\testpackage\*.java.
    • The full path of the current directory.
    • The value of CLASSPATH environment variable.
    • The error message.
    We renamed the email address from javadoc@sun.com to javadoc-tool@sun.com to emphasize that this address is for questions and comments about the tool itself, including the standard doclet, and the format it generates. This address is not for questions or comments about the content of the documentation it generates -- please submit bugs or comments about the content as described at email addresses for documentation content and bug submission form. The address javadoc@sun.com will continue to work, but won't be advertised.     		Sun
    Java Software