Sun’s tool for generating HTML (Hypertext Markup Language) 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
The comments look like this:
|Class Javadoc Tags
||Method Javadoc Tags|
Javadoc tags are for /** comments only. Don’t use them in or comments.
Canonical Javadoc Tag Order
You should keep @block tags within Javadoc comments in the following canonical
Sun does not officially define the order of order of: @author, @inheritDoc, @override or @custom
tags. Neither javac.exe not javadoc.exe issue error or
warning messages if your tags are out of order. The main reason to keep them in order is same reason you the
phone book is sorted alphabetically — to make it easier to find what you are looking for.
|Canonical Order of Javadoc tags|
You can generate the HTML with javadoc MyClass.java. the -notimestamp option stops it from timestaming the results. Timestamping creates false deltas which
will burden a version control system. If you want private methods also documented use:
javadoc.exe -breakiterator -charset "UTF-8" -private MyClass.java
javadoc.exe -breakiterator -charset "UTF-8" -package MyClass.java
-breakIterator use the newer way of computing where the first sentence of your Javadoc
-charset controls 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.
If you run out of RAM (Random Access Memory), expand the virtual memory space with:
javadoc.exe -breakiterator -charset "UTF-8" -J-mx64m -J-ms64m...
javadoc.exe -breakiterator -J-mx64000000 -J-ms64000000...
javadoc.exe *.java -d javadoc -breakiterator
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.
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
The OVERVIEW button shows you a short description of all the packages in the
The FIELD, CONSTR and METHOD
buttons let you jump right to that section for the current class.
- 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,
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 (Internet Explorer) 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. Note that this is not not a
/** comment and it contains no Javadoc. Note also the package comment contains no
Something has always disgusted me about Javadoc — that you are supposed to embed unreadable HTML markup in
your Java source program comments. This makes them often unusable for those who need them most. If you
don’t use entities and tags, the generated Javadoc HTML looks like a solid block of black mush.
Here is a classic example of what sort of a mess you source code looks like:
Would it not be so much nicer if could be coded like this in plain text Unicode:
Even when you perfectly encode your HTML entities and tags in your javadoc comments, the HTML that javadoc.exe generates is somewhat rank.
I suggest the following improvements in descending order of importance:
- Include a utf-8 charset declaration in the generated HTML.
- Clean up the code generator so the HTML it generates passes validation, provided the Javadoc comments
themselves are well-formed HTML.
- For a Javadoc comment without embedded HTML tags, treat them as if they had been enclosed in <pre> … </pre>
- Validate the HTML in Javadoc tags and complain about it if it is wrong.
- If the encoding of the generated HTML is embedded as utf-8, then there is no
need for accented character entities in the generated HTML. There is no need for entities either in the
Javadoc. You could encode awkward characters in your in your comments with or without entities.
- That leaves a handful of truly awkward characters: < > and &. Are they meant as HTML tag
delimiters or literally? What we need is a more readable convention to tell the two meanings apart. I suggest
we commandeer some obscure Unicode characters such as \u227a ≺ which looks much like < and \u227b ≻ which looks much like >. They won’t render in most fonts, because that does not matter. That is just the way
they are stored in Java source when you meant literal
< and > not embedded html tag delimiters. The IDE (Integrated Development Environment) can optionally
display them as ordinary < and > but in a
special colour, or use a font that supports them. Javadoc will convert them to < and >. All existing Javadoc that uses
HTML tags and entities will continue to work unmodified. If fonts are available that display them, these
obscure variants will work even unmodified. They seem to render OK in my browser with tiresias pcfont z font.
I will leave as an exercise for the reader to select a suitable proxy character for & and to ponder whether any other awkward characters need this special treatment. My guts
tell me in is unecessary to treat " specially.
- Define a canonical format for Javadoc comments and have IDEs (Integrated Development Environments)
reformat as a matter of course when source
code is tidied. This would include collapsing multiple blank lines to one, aligning the stars etc.
- More clearly document what sort of HTML you are and are not allowed to embed in kosher Javadoc
- Teach IDEs
the conventions so they warn you right away of malformed HTML in Javadoc comments, and Javac
treats them as warnings. This format might even become part of the JLS (Java Language Specification). (While we are at it, start gently
enforcing naming conventions as informational messages.)
- IDE tools to let you view the embedded Javadoc comments as Unicode chars, minimally encoded entities (just
crucial) or fully encoded entities (even entities that did not strictly need encoding). Internally the data
would be stored in the source file as Unicode/utf-8, and rendered HTML, as they
would look to someone browsing the Javadoc. This is purely a display rendering option. The source program does
- Javadoc was a lashup to demonstrate the concept of embedding program documentation in programs, and using
it to generate cross-indexed highly readable documentation. It has been a resounding success. It is one of the
main reasons Java has done so well. It is time to take second look at it and polish it so that it becomes an
utterly integral to all programs, not just those authored by the fastidious.
- Even if no one salutes, it is possible partically fix the problems with text processors that massage
the Java source, and massage the Javadoc output. All you need is a font that supports some proxy characters,
and a keyboard macro tool or keyboard firmware to generate them.
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 generated 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
- 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 Java version 1.2 or later 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
- 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
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.
Oracle’s JDK Tool Guide to javadoc.exe
Oracle’s Technote Guide on Doclets
Oracle’s JDK Guide to com.sun.javadoc Doclet API
Oracle’s JDK Tool Guide to fine points
Oracle’s JDK Tool Guide to Including arbitrary content into Javadoc
For an example of how not to write Javadoc see this classic Sun example.
It tells you the obvious yet never tells you what anything is for, and it fails to
point you to a place to learn the arcane HTTP (Hypertext Transfer Protocol) header field vocabulary.
Oracle’s Javadoc on Example of Bad Javadoc