Java Reference
In-Depth Information
When viewed in Microsoft Internet Explorer, this will appear similar to Figure 2-1.
Figure 2-1.
Example Javadoc output
■
Note
Javadoc is more powerful than many programmers realize. It was developed as an extensible tool,
which can behave in different ways depending on which module is plugged in. By default, it will parse the
Java source code, generating API documentation. But if you were to change the plug-in to XDoclet (
http://
xdoclet.sourceforge.net/
), for instance, the Javadoc engine could generate additional source code
based on comments in the code you wrote (very useful when building J2EE applications—you could have
XDoclet create your interfaces and deployment descriptors for you). Or you could plug in DocCheck
(
http://java.sun.com/j2se/javadoc/doccheck
), and you could get a report on how well you are
adhering to Sun's Javadoc conventions.
Coding Conventions
Sun published an article titled “How to Write Doc Comments for the Javadoc Tool,” which is
available online at
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
.
A quick overview of the topics covered in this article follows.
What to Write
The names of your classes and methods should be reasonably self-documenting, so there is
no point in writing Javadoc comments that just restate the name of the class or method. Your
Javadoc comments should provide information that will help the user of your class and/or
provide information that would be needed by a third party if they wanted to reimplement your
class from scratch (without looking at your source code).
