Sun’s tool for generating HTML documentation on classes by extracting
comments from the Java source code files. The tool is spelled javadoc.exe
all lower case, and the documents produced are spelled Javadoc.
You used to see JavaDoc and JavaDOC, but Sun has standardised on Javadoc
Javadoc Tags
The comments look like this:
Generating Javadoc
You can generate the HTML with javadoc MyClass.java .
If you want private methods also documented use:
javadoc.exe -breakiterator -charset "UTF-8" -private MyClass.java
If you run out of RAM, expand the virtual memory space with:
javadoc.exe -breakiterator -charset "UTF-8" -J-mx64m -J-ms64m...
if that does not work try:
javadoc.exe -breakiterator -J-mx64000000 -J-ms64000000...
-breakIterator use the newer way of computing where the
first sentence of your Javadoc ends.
-charset control the encoding of the generated files.
This will create Javadoc of everything in the current directory and put it in a
subdirectory of this one called javadoc. Without the -d, the Javadoc will all be
muddled in with your source.
javadoc.exe *.java -d javadoc -breakiterator
Praise
If you a have used C++, and found it so difficult to discover what a method does
or a type is, you will love Javadoc. You can easily find the documentation you
need, and it is right in the source where it is kept up to date. Creating html
Javadoc on your own unfinished code can help you see how the classes interact or
rapidly find the method you are after. The Javadoc utility also acts as a lint
on your Javadoc helping you get all the parameter names correct and complete.
Browsing Javadoc
Familiarise yourself with all the useful cross referencing information Javadoc
generates.
The USE button is amazing. It will tell you the place
other classes extend, implement, or use this class. It can help you figure out
what you can do with one of these objects, or how you create one when there is
no constructor.
The TREE button shows you the class hierarchy, what
inherits from what.
The INDEX button shows you all the fields and methods
in the entire package an alphabetical order.
The OVERVIEW button shows you a short description of
all the packages in the universe.
The FIELD, CONSTR and METHOD
buttons let you jump right to that section for the current class.
Gotchas
- the separator for elements of the -sourcepath and the -exclude
options are the : whereas the separator for elements
of the -classpath option is the ;.
- Javadoc needs the same classpath that was used to compile the source. It can’t
see any special jars added to javac.exe via -cp.
- Make sure you have freshly compiled and that there are no old stray class files
before you run Javadoc.
- Contrary to the documentation, you can’t produce Javadoc on source in jar
files. You have to expand them first. Similarly you can’t produce Javadoc
from jars of class files, not even rudimentary Javadoc. Javadoc.exe
is much pickier than Javac.exe about classes
being named precisely to match their directories and *.java names, including
case.
Bugs
Javadoc generates invalid anchor names that contain spaces, commas and
parentheses. If you link to them, you can replace the spaces with %20, but then
Opera and IE will not work. Netscape, Mozilla and Firefox will however.
Documenting a Package
Here is a how you document the package as a whole. Create a file called package-info.java
in the same directory as the other *.java files in the
package. Note the lower case and the dash. This is a deliberately illegitimate
class name. Eclipse won’t let you create it unless you tell Eclipse it as
a common file, not a class.
Make sure your Javadoc for the package as a whole comes right before the package
statement. Then run your Javadoc generate on the entire package as usual.
Tips
Before you write reams of Javadoc, look at some vaguely related topics, examples,
and generate some HTML to learn some of the fine points.
- @author and @version
are not officially permitted on individual methods, just classes and interfaces.
- There is no @copyright tag. Don’t include
copyright information on the @author tag. Embed it
in an ordinary comment at the very top before
the package statement. You can ensure your
copyright is displayed on all genenerated JavaDoc by embedding it in your
package template.
- Javadoc may include HTML tags. Make sure you use entities <
and > for < and > HTML tags have no
special meaning in ordinary comments. They won’t help beautifiers reflow
your comments nicely.
- Javadoc contains only information for clients of your classes and methods.
Don’t include implementation trivia or version history.
- Sun has documented all the methods in the standard class libraries. This is your
main source of information about how to use the standard classes.
- Generated Javadoc in JDK 1.2+ is quite different from 1.1, and easier to
navigate. Javadoc now automatically re-uses doc comments for some methods. If a
method in a class (C) or interface (I) has no comment or tags, Javadoc will
instead use the comment and tags from a method it either overrides or implements,
if any. For a method in class C, it does this by searching recursively through
all interfaces that class C implements, then through all superclasses of C. This
saves hours of propagating Javadoc comments.
- Java has no Eiffellian preconditions. The biggest problems are with Strings. Can
this method accept a null? Can it accept an empty string? can it accept a blank
string consisting only of whitespace chars (e.g. < 33)? I suggest the
following convention to inch us toward precondition Nirvana.
The USE Link
I had been using Javadoc for years and never noticed the USE
link at the top of some pages. If you click, it will tell you what other classes use
this class, e.g. have factory methods to construct these Objects,
have methods that use them as parameters, or that modify return modified
versions of them.
While you are there, explore the other useful Javadoc cross reference
information. docs\technotes\guides\javadoc
Learning More
Sun’s JDK Tool Guide to
javadoc.exe : available:
Sun’s JDK Technote Guide on
Doclets : available:
For an example of how not to write Javadoc see this classic Sun example.
Sun’s Javadoc on the
Example of Bad Javadoc class : available:
2006-03-04 by Roedy Green ©1996-2008 Canadian Mind Products
Please email your feedback for publication, errors, omissions, broken/redirected link reports
