Effective Java

---

CHAPTER 8
METHODS
260
One caveat should be added concerning documentation comments. While it is
necessary to provide documentation comments for all exported API elements, it is
not always sufficient. For complex APIs consisting of multiple interrelated
classes, it is often necessary to supplement the documentation comments with an
external document describing the overall architecture of the API. If such a
document exists, the relevant class or package documentation comments should
include a link to it.
Javadoc automatically checks for adherence to many of the recommendations
in this item. In Java 7, the command line switch -
Xdoclint
was required to get
this behavior. In Java 8 and 9, checking is enabled by default. IDE plug-ins such as
checkstyle go further in checking for adherence to these recommendations
[Burn01]. You can also reduce the likelihood of errors in doc comments by
running the HTML files generated by Javadoc through an 
HTML validity checker
.
This will detect many incorrect uses of HTML tags. Several such checkers are
available for download, and you can validate HTML on the web using the W3C
markup validation service [W3C-validator]. When validating generated HTML,
keep in mind that as of Java 9, Javadoc is capable of generating HTML5 as well as
HTML 4.01, though it still generates HTML 4.01 by default. Use the 
-html5
command line switch if you want Javadoc to generate HTML5.
The conventions described in this item cover the basics. Though it is fifteen
years old at the time of this writing, the definitive guide to writing doc comments
is still 
How to Write Doc Comments
[Javadoc-guide].
If you adhere to the guidelines in this item, the generated documentation
should provide a clear description of your API. The only way to know for sure,
however, is to