18.2

HTML in a Documentation Comment

DOCUMENTATION COMMENTS

the text of the comment has three lines. The first line consists of the text  

XYZ

 ;

the second line consists of the text  

Initialize to pre trial defaults.

and the third line consists of the text  

123

18.2   HTML in a Documentation Comment

Text in a documentation comment may use HTML markers for formatting, with

the exception that the specific markers

,

,

,

,

,

, and

 are reserved for use by the documentation generator and should not be used

in the text. A complete description of HTML is available from the web site

http://www.w3.org

 and also through the Internet documentation database at

http://www.internic.net

, where the document  Hypertext Markup Language

 Version 2.0  by T. Berners Lee and D. Connolly may be found as RFC1866.

18.3   Summary Sentence and General Description

The first sentence of each documentation comment should be a summary sen 

tence, containing a concise but complete description of the declared entity. This

sentence ends at the first period that is followed by a blank, tab, or line terminator,

or at the first tagline (as defined below). This simple rule means that a first sen 

tence such as:

This is a simulation of Prof. Knuth's MIX computer.

will not work properly, because the period after the abbreviation  

Prof

  ends the

first sentence, as far as the Java documentation comment processor is concerned.

Take care to avoid such difficulties.

Sentences following the summary sentence but preceding the first tagged

paragraph (if any) form the general description part of the documentation com 

ment.

18.4   Tagged Paragraphs

A line of a documentation comment that begins with the character

@

 followed by

one of a few special keywords starts a

tagged paragraph

. The tagged paragraph

also includes any following lines up to, but not including, either the first line of the

next tagged paragraph or the end of the documentation comment.

Tagged paragraphs identify certain information that has a routine structure,

such as the intended purpose of each parameter of a method, in a form that the

420