CHAPTER 18

Documentation Comments

The view that documentation is something that is
added to a program after it has been commissioned
seems to be wrong in principle, and counterproductive in practice.
Instead, documentation must be regarded as an
integral part of the process of design and coding.
—C. A. R. Hoare, Hints on Programming Language Design (1973)

Java programs can include documentation in their source code, in special documentation comments (§3.7). Such comments can appear before each class or interface declaration and before each method, constructor, or field declaration. Hypertext web pages can then be produced automatically from the source code of the program and these documentation comments.

This chapter gives an informal description of documentation comments. A complete formal specification would require a detailed description of those parts of the Hypertext Markup Language (HTML) that can be used within the documentation comments, which is beyond the scope of this specification.