18

C H A P T E R

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)

J

AVA programs can include documentation in their source code, in special doc 

umentation 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 docu 

mentation comments, which is beyond the scope of this specification.

18.1   The Text of a Documentation Comment

The text of a documentation comment consists of the characters between the

/**

that begins the comment and the

*/

 that ends it. The text is divided into one or

more lines. On each of these lines, leading

*

 characters are ignored; for lines other

than the first, blanks and tabs preceding the initial

*

 characters are also discarded.

So, for example, in the comment:

/**XYZ

** Initialize to pre trial defaults.

123*/

419