Javadoc : Java Glossary

Javadoc Tags

Javadoc tags are for /** comments only. Don’t use them in /* or // comments.

Canonical Javadoc Tag Order

Generating Javadoc

javadoc.exe -breakiterator -charset "UTF-8" -private MyClass.java

javadoc.exe -breakiterator -charset "UTF-8" -J-mx64m -J-ms64m...

javadoc.exe -breakiterator -J-mx64000000 -J-ms64000000...

-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

Browsing Javadoc

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

Documenting a Package

Yuch

Here is a classic example of what sort of a mess you source code looks like:

• Further, even if you do encode perfect HTML in your Javadoc with entities and balanced tags, the HTML generated will be not pass validation with HTML Validator. There are even gross errors such as unbalanced tags.
• It is missing an encoding tag.
  <meta http-equiv="Content-Type" content="text/html; charset=iso- utf-8">
  or
  <meta http-equiv="Content-Type" content="text/html; charset=8859-1">
• It does not translate all awkward characters into entities.
• It uses old-style upper-case tags.
• It excessively uses explicit HTML attributes rather than deriving the formatting from a CSS style sheet with elegant markup.

1. Include a utf-8 charset declaration in the generated HTML.
2. Clean up the code generator so the HTML it generates passes validation, provided the Javadoc comments themselves are well-formed HTML.
3. For a Javadoc comment without embedded HTML tags, treat them as if they had been enclosed in <pre> … </pre>
4. Validate the HTML in Javadoc tags and complain about it if it is wrong.
5. 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.
6. That leaves a handful of truly awkward characters: &lt; &gt; and &amp;. 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 can optionally display them as ordinary < and > but in a special colour, or use a font that supports them. Javadoc will convert them to &lt; and &gt;. 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.

7. Define a canonical format for Javadoc comments and have IDEs reformat as a matter of course when source code is tidied. This would include collapsing multiple blank lines to one, aligning the stars etc.
8. More clearly document what sort of HTML you are and are not allowed to embed in kosher Javadoc comments.
9. 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. (While we are at it, start gently enforcing naming conventions as informational messages.)
10. 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 not change.
11. 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.
12. Even if no one salutes, it is possible partically fix the 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.

Tips

• @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 &lt; and &gt; 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

While you are there, explore the other useful Javadoc cross reference information. docs\technotes\guides\javadoc

Learning More

For an example of how not to write Javadoc see this classic Sun example.