Documentation Comments

Documentation Comments

Java has support for special comments documenting types (classes and interfaces), fields ( variables ), constructors, and methods , hereafter referred to collectively as declared entities. The javadoc program can then be used to automatically extract these comments and generate formatted HTML pages.

A documentation comment should immediately precede the declared entity, with no blank lines in between. The first line of the comment should be simply the characters /** with no other text on the line, and should be aligned with the following declared entity. Subsequent lines consist of an asterisk, followed by a single space, followed by comment text, and aligned with the first asterisk of the first line. The first sentence of the comment text is special, and should be a self-contained summary sentence. A sentence is defined as text up to the first period that is followed by a space, tab, or newline. Subsequent sentences further describe the declared entity.

The comment text can include embedded HTML tags for better formatting, with the exceptions of the following tags: <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, <HR>.

Following the comment text are the documentation tag lines. A documentation comment should include all the tags that are appropriate for the declared entity.

Class and interface comments can use the @version, @author, and @see tags, in that order. If there are multiple authors, use a separate @author tag for each one. Required tags: none.

Constructor comments can use the @param, @exception, and @see tags, in that order. Required tags: one @param tag for each parameter, and one @exception tag for each exception thrown.

Method comments can use the @param, @return, @exception, and @see tags, in that order. Required tags: one @param tag for each parameter, one @return tag if the return type is not void, and one @exception tag for each exception thrown.

Variable comments can use only the @see tag. Required tags: none.

A documentation comment ends with the characters */. It is also acceptable to end the comment with the characters **/ to aid in visual identification of the documentation comment.



Software Development. Building Reliable Systems
Software Development: Building Reliable Systems
ISBN: 0130812463
EAN: 2147483647
Year: 1998
Pages: 193
Authors: Marc Hamilton

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net