Javadoc : Java Glossary

Javadoc
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
Javadoc Tags Documenting a Package
Canonical Javadoc Tag Order Yuch
Generating Javadoc Tips
Praise Use Link
Browsing Javadoc Learning More
Gotchas Links
Bugs

Javadoc Tags

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 order:
Canonical Order of Javadoc tags
tag In Class
Comment
In Method
Comment
@author
@inheritDoc
@override
@param
@return
@throws
@version
@see
@since
@serial
@serialData
@serialField
@deprecated
@custom tags
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.

Generating Javadoc

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

rem or for default, protected, and public
javadoc.exe -breakiterator -charset "UTF-8" -package MyClass.java

-breakIterator use the newer way of computing where the first sentence of your Javadoc ends.

-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

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

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 (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 @tags.

Yuch

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:
  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 (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 &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 (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.
  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 (Java Language Specification). (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 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

Before you write reams of Javadoc, look at some vaguely related topics, examples, and generate some HTML to learn some of the fine points. 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

Oracle’s JDK Tool Guide to javadoc.exe : available:
Oracle’s Technote Guide on Doclets : available:
Oracle’s JDK Guide to com.sun.javadoc Doclet API : available:

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

Oracle’s Javadoc on Example of Bad Javadoc : available:
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.
@Override
annotations
Askelon
canonical
comments
Doclet
Doxygen
Eiffel
factory method
gjdoc: Javadoc replacement that generates validated XHTML
jdocs.com: Javadocs on everything, including non-Sun classes, also Wiki
Obsoft
Oracle’s Javadoc style guide
rDoc
tools

available on the web at:

http://mindprod.com/jgloss/javadoc.html
ClustrMaps is down

optional Replicator mirror
of mindprod.com
on local hard disk J:

J:\mindprod\jgloss\javadoc.html
logo
Please the feedback from other visitors, or your own feedback about the site.
Contact Roedy.
Blog
IP:[65.110.21.43]
Your face IP:[54.227.156.177]
You are visitor number 82,009.