Java Reference
In-Depth Information
Chapter 19. Documentation Comments
Any member introducing a dog into the Society's premises shall be
liable to a fine of £10. Any animal leading a blind person shall be
deemed to be a cat.
Rule 46, Oxford Union Society (circa 1997)
Documentation comments, usually called
doc comments,
let you associ-
ate reference documentation for programmers directly with your code.
The contents of the doc comment can be used to generate reference doc-
umentation, typically presented using
HTML
.
Doc comments are generally designed as fairly terse reference docu-
mentation. The reference documentation typically covers the contract
of the documented interface, class, constructor, method, or field to the
level of detail most programmers need. This approach is distinct from a
full specification, which can be too long for reference documentation. A
full specification might devote several pages of text to a single meth-
od, whereas reference documentation might be one or two paragraphs,
possibly even short ones. Specifications should be produced separately,
although they can be cross-referenced by the doc comment, as you will
soon see.
[1]
[1]
This distinction is blurring and, for better or worse, documentation comments are being used to define
full specifications.
The procedure for generating documentation from the doc comments
varies among development environments. One common procedure is to
run the
javadoc
command on the packages or types; hence, the gener-
ated documentation is often called
javadoc.
This chapter teaches what can go into documentation comments and how
the contents are interpreted. You will also learn about features that are,
strictly speaking, outside the language but are conventions for creating
the generated documentation, such as overall package documentation
and the location for images and other resources. Your development en-
