 Downloads
Community
|
- A. Using the Javadoc Tool
- B. Troubleshooting: Bugs, Errors and Warnings
- C. Customizing the Javadoc Tool
- D. Developing with the Javadoc Tool
- E. Javadoc 1.1 Only
- F. Doclets
- G. Taglets
- H. Third Party Tools for Javadoc Tool
- I. Third Party Tools for Java and Other Languages
| |
| B. Troubleshooting: Bugs, Errors and Warnings |
| B1. |
What bugs are in Javadoc?
|
| B2. |
How do I submit bugs and feature requests?
|
| B3. |
How do I redirect error messages to a file?
|
| B4. |
I just can't get Javadoc to work over my entire source code; what do you suggest?
|
| B5. |
I run out of memory -- how much is needed, exactly how do you call Javadoc,
and how long does it take?
|
| B6. |
Why aren't the memory flags (-J-m) recognized in Windows?
|
| B7. |
When I run Javadoc on my source package, some links are not generated.
|
| B8. |
In Javadoc 1.2.2, when using @see or {@link} tags to external API,
and links to methods, fields and constructors are missing.
|
| B9. |
Why do I get the warning "Class or Package not found in @see/@link tag" or "reference not found"?
|
| B10. |
The class comments are missing from the generated docs, but are in
the source code.
|
| B11. |
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?
|
| B12. |
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.
|
| B13. |
I am documenting 33 packages and added a new package to my javadoc command
but this created a "No source files" error.
|
| B14. |
I get the error "Class xxx already defined".
|
| B15. |
I get the errors "FileNotFoundException" and "Fatal Exception".
|
| B16. |
Using Javadoc 1.4.1, I get an InvocationTargetException when I set
the classpath.
|
| B17. |
Why do I get so many @serial warnings,
including warnings about private fields?
|
| |
| H. Third Party Tools for Javadoc Tool |
|
|
| |
| I. Third Party Tools for Java and Other Languages |
|
|
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 Tool Home Page has links to all
documentation and related information on the Javadoc tool, including
proposed Javadoc tags.
A2. How do I write Javadoc doc comments and tags?
To get details on how to write Javadoc
tags and documentation comments, this is the best place at Sun to start:
If your doc comments comprise an API specification, you might find this
document useful:
- Requirements for Writing
API Specifications - Standard requirements used when writing
the Java 2 Platform Specification. It can be useful whether you
are writing API specifications in source file documentation
comments or in other formats. It covers requirements for packages,
classes, interfaces, fields and methods to satisfy testable assertions.
A3. How do I run Javadoc?
There are two ways to run Javadoc -- on classes and on packages.
The examples at the end of the Javadoc Tool Reference Doc
describes both ways:
Javadoc 1.1 has some important bugs, so if using that version,
it is imperative to read the Javadoc 1.1 Only
section 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 .java source files in the same directory hierarchy as they are
in when you compile.
Once you've run Javadoc and want to view the generated HTML, the topmost
page is named index.html (or packages.html
in Javadoc 1.1).
A4. How do I run Javadoc from within a Java application?
Starting with version 1.4.0, Javadoc has a programmatic interface
in the form of an execute method. See
Programmatic interface to Javadoc.
your_method() {
// your code
String[] javadocargs = { "-d", "docs",
"-sourcepath", "/home/user/src",
"java.applet" };
com.sun.tools.javadoc.Main.execute(javadocargs);
// your code
}
|
For Javadoc 1.2.x and later, you can call main:
your_method() {
// your code
String[] javadocargs = { "-d", "docs",
"-sourcepath", "/home/user/src",
"java.applet" };
com.sun.tools.javadoc.Main.main(javadocargs);
// your code
}
|
The disadvantages of calling main are:
(1) It can only be called once per run -- for 1.2.x or 1.3.x,
use java.lang.Runtime.exec("javadoc ...")
if more than one call is needed,
(2) it exits using Systme.exit(),
which exits the entire program, and
(3) an exit code is not returned.
For Javadoc 1.1.x, drop com (above) and instead use
sun.tools.javadoc.Main.main(javadocargs);.
A5. 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"
A6. 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:
- Use the
@file
option to place the package or source filenames in a separate file.
- On Windows, here is a Windows shell script.
Save it to disk (in our example we call it
run-javadoc.bat),
then run it (run-javadoc.bat).
- On Solaris, write a shell script to hold the entire command,
save it to a file, make the file executable, then run it.
For example, here is a Solaris shell script.
Save it to disk (in our example we call it
run-javadoc),
make it executable (chmod a+x run-javadoc),
then run it (run-javadoc).
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
A7. I'm planning to upgrade to a newer version
of Javadoc and am wondering what kinds of problems I might
encounter?
Please read the
1.4 possible incompatibilities and
1.2 possible incompatibilities of What's New in Javadoc.
Javadoc 1.2 and later versions have been through a much more rigorous
design and testing program than 1.1, and have proven to be much more
reliable and robust.
We have also been careful to write each verison Javadoc 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 earlier versions.
Please let us know of any other incompatibilites you run across.
A8. Is there an easy way to print the many pages
generated from Javadoc, such as PDF? Sun currently provides the API docs
only in HTML, which is not easily printable.
Which route you go depends on whether you (1) have the source files
and are willing to re-generate the documentation, or (2) simply want
to print the HTML files (perhaps by converting them first to PDF).
- The following two doclets require that you have the source files
and convert those doc comments to PDF.
PDF Doclet
- Someone has written a PDF Doclet that converts doc comments in
source files to a PDF document. We have not tried it, so cannot
vouch for it. Please let us know your experience with it.
As we understand it, the styles are fixed.
MIF Doclet
- If you want high quality and 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 PDF (or PS) and print directly to a printer
with a single command. You have a lot of flexibility to change
the styles however you want.
- The following programs convert the HTML files to Postscript or PDF.
HTMLDOC.
- Probably the simplest way (but not necessarily free)
is to use HTMLDOC.
A user has written in to say it's a great program for converting the
javadoc-html to a nice postscript- or pdf-document.
It runs on Windows and Unix, and there is a free demo
Windows version which seems to be fully functional except
cannot be run from the command line (for batch processing or
providing conversions from a webserver).
html2ps
- 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.
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:
- 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).
- Concatenate the HTML files together in the order you
want them printed.
- 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.
A9. 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:
- Incremental Build -
If you want to run Javadoc on package
p1 and separately run Javadoc
on package p2, integrating them into a single document with one overview
page and one index page, this is not currently possible. We call this
incremental
build and are considering it for a future release.
- Linking Documents -
However, anytime you run Javadoc, you can use the
-link or
-linkoffline options to make it link to pre-existing documents
generated from Javadoc. For example, since every class inherits from
java.lang.Object, you can link to that class on our website
if you'd like. All that is required is that those exisiting documents contain
a file named package-list that lists the packages at that location.
(Javadoc 1.2 and later versions automatically generate this file, located in the
document's root directory, which also holds index.html.) When Javadoc
encounters a package not specified on the command line, it will look in the specified
package-list files for that package and link to it.
- Inheriting Comments from J2SE -
Your code can also automatically inherit comments from interfaces and classes in
the J2SE. You can do this by unzipping the src.zip file that ships with the
SDK (it does not contain all source files, however), and add its path to -sourcepath.
When javadoc runs on your code, it will load the doc comments from those source files
as needed. For example, if a class in your code implements java.lang.Comparable,
the compareTo(Object) method you implement will inherit the doc comment from
java.lang.Comparable.
A10. I'm using -link or -linkoffline but some
of my external links do not show up. Why is this?
NOTE: See the related FAQ Why do
I get the warning "Class or Package not found in @see tag"
or "reference not found"?
NOTE: In 1.4.2 we have removed the import limitation described
below by allowing links to any fully-qualified class pointed
to with the -link option.
For the related bug fix, see:
4662658:
With -link, all @see/@link tags should create links to excluded classes
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.4 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 limitation in Javadoc. For a link to an external referenced class
to actually appear, the class must be referenced in a particular way:
- In 1.2.x and 1.3.x, it must be referenced explicitly by name
in either a declaration or an import statement.
- In 1.4.x, the rules have been relaxed slightly -- it must be
referenced by a declaration or any kind of import statement
(by wildcard, explicitly by name, or automatically for
java.lang.*).
Note that it is not sufficient for it to be referenced in the body of
a method. 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.io.File; // workaround to enable @see/@link hyperlink
The wildcard import statement import java.io.*
works starting with 1.4.0. We strongly recommmend you add a
comment similar to the one shown above to the right of the import
statement, so the reason for the import statement can be understood,
and can be removed if the Javadoc limitation is removed.
This limitation is further described at
How a Class Must Be Referenced for a Link to Appear
A11. 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:
- Use relative links with
-link or -linkoffline
and require documentation set B to be located relative to set A
(On Solaris, these can be non-relative locations provided you
use a symlink to perform the redirect.)
- Write a script to change the hard-coded links in set B to the required
hard-coded links
- Replace the hard-coded links with a programmable link (Javascript?
Applet tag? Object tag?) that could perform a redirect at runtime.
We have not pursued this solution.
Someday when browser source is XML rather than HTML, dynamic redirects
may be possible.
A12. 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.
A13. 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.
A14. How can I create custom Javadoc tags?
Javadoc 1.4 solves this problem with the
-tag option to
create simple tags and the
-taglet option for complex
tags (tags with more than one argument, or that require special
HTML formatting on output).
To do this in earlier versions of Javadoc, it will take some
creative programming on your part. You can start by looking
at the example at How can I modify the standard doclet.
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 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)
A15. 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
A16. 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 Javadoc option to hide, exclude or suppress
public members from the javadoc-generated documentation.
If you want to exclude public classes or interfaces, you
can do so by passing into javadoc only the source filenames
for all classes you want to document, and exclude those
you want to omit. Notice this has the granularity of files,
not classes. (You can put the list of classes in a
command
line argument file rather than directly on the command line.)
Javadoc offers no way to omit classes when
passing in package names on the command line.
We are considering @exclude
as a proposed tag for excluding members.
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 Javadoc Birds-of-a-Feather session?
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.
A19. How do I generate documentation for packages that contain a package.html file but no java files?
Technically, that's currently not possible -- however,
there is a practical workaround, where you include a package-private
"placeholder" class in that package. So long as you don't use either
the -private or -package option, the class will never appear in your
documentation.
/**
* Exists only to enable package.html to be included in javadoc
*/
class Placeholder {
}
|
This is being tracked by
Bug 4492654
We hope to remove this restriction.
Troubleshooting: Bugs, Errors and Warnings
B1. What bugs are in Javadoc?
There are several places to look for reports of Javadoc bugs and feature
requests:
- This FAQ - For Javadoc 1.1 and 1.2, the most commonly
encountered bugs are listed in this FAQ, along with workarounds
where possible.
- Release Notes - Some major known bugs for 1.4 are listed in
its 1.4 Release Notes.
(Nothing about Javadoc bugs is mentioned in the 1.2 or 1.3
Release Notes.)
- What's New in Javadoc - 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.4, 1.3, 1.2.2 and 1.2.
B2. How do I submit bugs and feature requests?
When submitting a bug, be prepared to describe the steps and supply
the source files needed to reproduce the bug (or do the best you can).
We welcome your bug reports. If you have trouble with this bug
submission process, please email us directly.
- Go to Report a Bug or
Feature Request. Scroll to the bottom, check the checkbox
and click "Start a New Report".
- Scroll down to "Select a product or tool". In the pop-up
menu, for Javadoc bugs, under the "J2SE" heading, choose
Java 2 JRE/SDK, Standard Edition, (J2SE v1.2.x, 1.3.x, 1.4.x)
- Choose an operating system (don't choose "Generic/Other",
as it won't let you submit a bug) and appropriate category (bug, request
for enhancement, or ease of use), then click "Continue to next page".
- On the next page under "Subcategory", choose:
javadoc - Java API Documentation Generator Tool
if submitting a bug or feature in any part of Javadoc tool,
standard doclet, Doclet API or Taglet API in the Java 2 SDK.
Custom Doclets Bug - You can also submit bugs against custom
doclets such as the MIF Doclet, DocCheck Doclet, Localization
Doclet and any others except the standard doclet. In step 2 above,
these have their own category "Custom Doclets for the Javadoc
Tool" under "Other Technologies".
B3. How do I redirect error messages to a file?
In Windows NT/2000/XP and in Bourne (sh) and Korn (ksh) shells, you
can redirect the standard message stream by using the ">" operator,
and redirect the error messages stream by using the "2>" operator.
For example, 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" or "error". (This is easier for Javadoc 1.3
and earlier, because the filename being processed appears in
the standard output rather than the error output. However,
starting with 1.4, the filename now appears on the same
line as the error message.) For example:
C:> javadoc -d docs java.lang >javadoc.log 2>&1
You can redirect standard and error messages in C shell (csh)
and T shell (tcsh) by using ">&", such as:
C:> javadoc -d docs java.lang >&javadoc.log
The MS-DOS shell in Windows 95/98/ME does not allow redirection
of steams. You must use a shell that does, such as Cygwin or MKS.
B4. 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:
- Unset your classpath (Solaris, Windows). If you're using Javadoc 1.1,
make sure your API does not contain underscore
or other characters outside of A-Z, a-z, 0-9 and period (.).
- Try running javadoc on a single source file just to see if your setup
is correct. For class MyClass in mypackage, it should generate a class file
named "mypackage.MyClass.html" (for 1.1) or "mypackage\MyClass.html" (for 1.2)
containing documentation for the class,
plus a class hierarchy "tree.html" containing that one class,
and an index "AllNames.html" (for 1.1)
or "index-all.html" (for 1.2, without -splitindex) or "index-1.html" (for 1.2
with -splitindex) containing the members of that class.
In Javadoc 1.1, the links to bullet and heading images will all be broken links
unless you copy the images directory to where your HTML files are located (as
described elsewhere in this FAQ).
- Then try running javadoc on a single package, which will also generate
a package file "Package-mypackage.html" (for 1.1) or "package-summary.html" (for 1.2).
Source files should be in directories with the same names as the packages.
Thus, the file MyClass.java should be in a directory called "mypackage".
- If that succeeds, then try it on multiple packages.
B5. 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.
B6. 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
B7. 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.
B8. In Javadoc 1.2.2, when using @see or {@link} tags to external API, any 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.
B9. Why do I get the warning "Class or Package not found
in @see/@link tag" or "reference not found"?
NOTE: See the related FAQ I'm using -link
or -linkoffline but some of my external links do not show up.
Why is this?"
NOTE: In 1.4.2 we have removed the import limitation described
below by allowing links to any fully-qualified class pointed
to with the -link option.
For the related bug fix, see:
4662658:
With -link, all @see/@link tags should create links to excluded classes
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 one of these
warnings:
javadoc: warning - Class or Package not found, in @see tag: xxx
warning - Tag @see: reference not found: java.util.List
warning - Tag @link: reference not found: java.util.List
The following source file Test.java generates a warning
because JSplitPane is not referenced in either the declaration or
in an import statement.
/**
* @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.
Only one of the import statements is needed, depending on the
version of Javadoc you are using.
The wildcard import javax.swing.* statement is sufficient
in 1.4.x.
The explicit import javax.swing.JSplitPane statement is
required in 1.2.x and 1.3.x.
import javax.swing.*; // 1.4 workaround to enable @see link
import javax.swing.JSplitPane; // 1.2 and 1.3 workaround to enable @see link
/**
* @see JSplitPane
*/
public class Test {
}
|
Workaround - Include a reference to the Java name you want to include,
such as importing the class explicitly.
B10. 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.
B11. 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.
B12. 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.
B13. 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
command
line 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).
B14. 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.
B15. 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.
B16. Using Javadoc 1.4.1, I get an InvocationTargetException when I set
the classpath.
Using Javadoc 1.4.1, I require that the classpath contain j2ee.jar (for
the servlet library), but everytime I add that to the javadoc command,
it returns the InvocationTargetException below.
javadoc -classpath c:\j2sdkee1.3.1\lib\j2ee.jar -d ..\docs\ *.java
Constructing Javadoc information...
Standard Doclet version 1.4.1
Generating ..\docs\constant-values.html...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating ..\docs\overview-tree.html...
Generating ..\docs\index-all.html...
...
Generating ..\docs\AADSHomeServlet.html...
javadoc: In doclet class com.sun.tools.doclets.standard.Standard, method start
has thrown an exception java.lang.reflect.InvocationTargetException
java.lang.NullPointerException
at java.util.zip.ZipFile.getInputStream(ZipFile.java:184)
at com.sun.tools.javadoc.PackageDocImpl.documentation(PackageDocImpl.jav
a:71)
at com.sun.tools.javadoc.DocImpl.comment(DocImpl.java:74)
|
Solution - Upgrade to Javadoc 1.4.2. Javadoc 1.4.1 has a
bug where it tries to read package.html from the jar
file without checking if it is really in there. This bug has been
fixed in 1.4.2 as
4697040:
javadoc is reporting errors when classpath jar files have package.html files.
If you must use 1.4.1, and are forced to put that jar file on the
classpath, then open the jar file and put a valid package.html file
at the package directory being documented, then jar it back up.
For example, if documenting com.package1, then make sure
the jar file contains com/package1/package.html.
FYI, the InvocationTargetException is just a wrapper for all exceptions
thrown as a result of method invocation -- in this case, the start
method. For instance methods, the "target" is an object, and for class methods,
the "target" is a class.
B17. 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.
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:
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 <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.
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 <I>values</I> 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
<path>/com/sun/tools/doclets/standard/tags
and then use these options to javadoc:
-tagletpath <path>
-taglet com.sun.tools.doclets.standard.tags.ParamTaglet
This taglet will override the built-in ParamTaglet.
Developing with the Javadoc Tool
D1. 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 release for the Java software development kit (SDK),
available at:
(Apparently 1.1 is no longer available.)
For versions of the standard doclet prior to 1.4, the standard doclet
source code can also be downloaded separately as part of the documentation
download bundle:
D2. 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).
Javadoc 1.1 Only
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".
- We translate the doc comments
with a pair of doclets: (1) a pre-processing doclet that extracts the text
from the source files into comment files that are more easily
translated, and (2) a post-processing modification to the standard
HTML doclet that Javadoc uses to import the translated text from
the comment files into the generated documentation.
- We translate
the "labels"by translating the file
com/sun/tools/javadoc/resources/standard.properties
found in lib/tools.jar. For example, the Japanese file
is com/sun/tools/javadoc/resources/standard_ja.properties.
Note that if you are translating into Japanese, this translated file
is already provided in the Java 2 SDK, Standard Edition.
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.
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
- Doclet.com - website of third-party doclets
Doclet.com contains links to
documentation, articles, tools, and third-party doclets.
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. - Useful for GNU Emacs and GNU/Linux
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
- DocLint Doclet - Checks doc comments
DocLint
is a doclet that checks doc comments for missing comments and other
documentation discrepancies.
- JDiff Doclet - Generates difference between two sets of API.
JDiff Doclet
generates an HTML report of all the packages, classes, constructors,
methods, and fields, including their documentation, which have been
removed, added or changed when two APIs are compared.
Great for reporting what APIs have changed between two releases of your
product.
- Bouvard Doclet - Generates documentation for the Pecuchet browser for more effective exploration.
Bouvard Doclet
generates documentation in a format for the Pecuchet browser
expressly designed for more effective exploration.
This doclet and browser allow you to:
- graphically depict the relationships among classes and interfaces,
using user's selection to focus on a reduced set of elements
- rapidly find a class, interface, field, constructor or method
by simply typing its partial name while the global index automatically
positions itself.
- filter the visible elements according to their type and attributes
- organize information with flexibility, choosing the preferred
combination of lists, graphics and text
- DocBook Doclet - Generates DocBook SGML or XML documentation.
DocBook Doclet
is a doclet that allows you to generate reference handbooks
from doc comments for printed documentation. It supports:
- DocBook SGML 3.1 and 4.1
- DocBook XML 4.1.2
- Overview Comment Files
- Package Comment Files
Please send comments to Michael Fuchs.
- yDoc Doclet - Lets you exclude elements, generate UML diagrams and define custom tags using XML
yDoc is a
doclet that let's you:
- exclude classes, fields, and methods by adding an
exclusion tag (y.exclude), and also allows for sophisticated
custom filter criteria
- define custom tags via an XML based mechanism
- automatically generate and incorporate UML class diagrams
in your API
The UML generation is yDoc's main purpose and will be
constantly improved and enhanced.
- Classdoc - Not a doclet, but a program that lets
you generate API documentation from class files
See classdoc
- Ashkelon - An online API reference tool providing a
single, fully cross-referenced, searchable database repository.
Ashkelon -
An online reference tool for api documentation. Ashkelon is
javadoc taken to the next step of being able to reference
multiple APIs (>100,000 methods) in a single, fully
cross-referenced and searchable database repository.
It contains a doclet for getting data into the database.
Ashkelon is used to publish a number
of Jakarta APIs on the site dbdoc.org.
- JUnit Doclet - Helps developers with generating and
maintaining JUnit tests.
JUnit Doclet -
Incremental behaviour keeps modified code when regenerating.
Assists with refactorings (no tests get lost when renaming,
moving, etc.). See this article explaining the use of JUnit:
"Testing Without Excuses -
Diligent but routine pieces of work for JUnit should be the
computer's task." (33K, PDF)
- PDF Doclet - Generates PDF from doc comments in source files
PDF Doclet
- Someone has written a PDF Doclet that converts doc comments in
source files to a PDF document. We have not tried it, so cannot
vouch for it. Please let us know your experience with it.
As we understand it, the styles are fixed.
- Ja Doclet, JaDocs Packager, JaDocs - Generates XML output, with GUI front-end, viewer and finder
JaDoclet is a Javadoc doclet that creates XML output. JaDoclet creates an
XML file for each package plus an optional "packageset" file to hold
information that pertains to more than one package. The XML created is
otherwise similar to that created by the
Sun XML Doclet.
Those interested can find an explanation of JaDoclet and its output
formats at, or go directly to
sample output files
and
sample package set
.
JaDocs Packager is a GUI application that launches javadoc with JaDoclet.
The Packager supports most of the relevant javadoc command line options
through its visual interface, and can store and re-use sets of options. In
addition, Packager can convert existing javadoc-created HTML into the
JaDoclet XML format.
JaDocs
itself is a combination of a Packager, a Viewer, and a Finder. The
Viewer provides viewing features that aren't available with "Javadoc" HTML,
and represents a significant improvement, as stated by its author.
- Bookmark Doclet - Generates HTML files for import into
Netscape or Mozilla bookmarks
Bookmark
Doclet has been released by Bright Ring Software LLC under the GNU Public License.
This doclet does not generate API documentation; instead, it generates HTML
files that can be imported into Netscape or Mozilla bookmarks.
The bookmarks refer to online Javadoc documentation generated by the standard
doclet. Their multiple levels mirror the package structure of the underlying
code. For an example, see
Bookmark
file for JDK 1.4.1.
Taglets
DISCLAIMER: We do not test, endorse or guarantee the utility or fitness
of this software. Use at your own risk.
Taglets From Third Parties
@ru.k2s.example
Taglet - Enables the insertion of code examples.
The first sentence of the tag's text is a lead-in sentence;
the rest is an example that is displayed in code font and
enclosed with a border. Examples are allowed everywhere from
the overview down to the fields and methods. Inline
{@link} tags are processed by the taglet too.
Taglet is free for any use. 
Third Party Tools for Javadoc Tool
DISCLAIMER: We do not test, endorse or guarantee the utility or fitness
of third-party software. Use at your own risk.
- Scripts to recurse over source directories.
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).
- Download the source file
GetAllSubPackages.java. Compile it:
C:> javac GetAllSubPackages.java
- Build a file containing a listing of package names, where each
rootdir is a directory where package directories are rooted:
C:> java GetAllSubPackages packages.txt rootdir1 rootdir2 rootdirN
For example, if your package is com.myCompany.myPackage, located
at C:\source\com\myCompany\myPackage:
C:> java GetAllSubPackages packages.txt C:\source
- 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.
- 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.
- 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
- Utility for writing doc comments: Doc+.
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 wit |
