Project Analysis and Design - SCJD Exam with J2SE 5 - page 38

■

Note Javadoc produces output conforming to HTML standard 3.2, which does not require closing tags for
certain elements (e.g., there is no requirement for the <li> tag to be closed with a </li> tag, nor for the
<p> tag to be closed with a </p> tag); however, you may use them if you wish. In addition, the HTML 3.2
standard does not specify whether tags should appear in upper- or lowercase. Throughout this topic we will
use HTML 3.2 tags, but we will format them according to the later HTML 4.0 and XHTML formats (we will
use closing tags, and we will put the tags in lowercase). You may also use tags and HTML constructs that
were only created in HTML version 4 or later if you wish (Javadoc will handle them without problems). How-
ever, if you do so, you may find that some older browsers may not be able to display your generated
documentation.

There are many more HTML codes you may use in your Javadoc comments. You generally
don't need many of them, though, as you are generating API documentation for other pro-
grammers to read.

Tip You should use the <code> tag for Java keywords, package names, class and interface names,
method names, field names, and argument names to make them appear in monospaced font when the
browser supports it.

■

In addition to the HTML tags, Javadoc recognizes special Javadoc tags —and they will be
handled in special ways. The Javadoc tags for classes and interfaces are shown in Table 2-5.
The tags are listed in the order they should appear in your Javadoc comment.

Table 2-5. Class and Interface Tags

Tag Description

@author The name of the person who wrote the class or interface.

@version The current version of the class or interface. You might

choose to have your revision control software set this
automatically as you check your code out of source control.

@see Generates a link to the specified class or method—the link

will appear in a special “See Also” section of the generated
Javadoc. Refer to the comments below regarding the @see and
@link tags for special instructions.

@since Used to indicate the version number of your release in which

this class first appeared.

@deprecated Used to indicate that a class should no longer be used but still

exists for compatibility reasons. The tag should be followed by
text indicating what class the user should use instead of this
class, or “No replacement” if there is no class with
replacement functionality.