Embedded HTML
Javadoc passes HTML commands through to the generated HTML document. This allows you full use of HTML; however, the primary motive is to let you format code, such as: Feedback
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
You can also use HTML just as you would in any other Web document to format the regular text in your descriptions: Feedback
/**
* You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
Note that within the documentation comment, asterisks at the beginning of a line are thrown away by javadoc, along with leading spaces. Javadoc reformats everything so that it conforms to the standard documentation appearance. Don’t use headings such as <h1> or <hr> as embedded HTML, because javadoc inserts its own headings and yours will interfere with them. Feedback
All types of comment documentation—class, variable, and method—can support embedded HTML. Feedback
Some example tags
Here are some of the javadoc tags available for code documentation. Before trying to do anything serious using javadoc, you should consult the javadoc reference in the downloadable JDK documentation to get full coverage of the way to use javadoc. Feedback
@see: referring to other classes
The @see tag allows you to refer to the documentation in other classes. Javadoc will generate HTML with the @see tags hyperlinked to the other documentation. The forms are: Feedback
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
Each one adds a hyperlinked “See Also” entry to the generated documentation. Javadoc will not check the hyperlinks you give it to make sure they are valid. Feedback
{@link package.class#member label}
Very similar to @see, except that it can be used inline and uses the label as the hyperlink text rather than “See Also.”
{@docRoot}
Produces the relative path to the documentation root directory. Useful for explicit hyperlinking to pages in the documentation tree.
{@inheritDoc}
Inherits the documentation from the nearest base class of this class into the current doc comment.
@version
This is of the form:
@version version-information
in which version-information is any significant information you see fit to include. When the -version flag is placed on the javadoc command line, the version information will be called out specially in the generated HTML documentation. Feedback
@author
This is of the form:
@author author-information
in which author-information is, presumably, your name, but it could also include your email address or any other appropriate information. When the -author flag is placed on the javadoc command line, the author information will be called out specially in the generated HTML documentation. Feedback
You can have multiple author tags for a list of authors, but they must be placed consecutively. All the author information will be lumped together into a single paragraph in the generated HTML. Feedback
@since
This tag allows you to indicate the version of this code that began using a particular feature. You’ll see it appearing in the HTML Java documentation to indicate what version of the JDK is used. Feedback
@param
This is used for method documentation, and is of the form:
@param parameter-name description
in which parameter-name is the identifier in the method parameter list, and description is text that can continue on subsequent lines. The description is considered finished when a new documentation tag is encountered. You can have any number of these, presumably one for each parameter. Feedback
@return
This is used for method documentation, and looks like this:
@return description
in which description gives you the meaning of the return value. It can continue on subsequent lines. Feedback
@throws
Exceptions will be demonstrated in Chapter 9. Briefly, they are objects that can be “thrown” out of a method if that method fails. Although only one exception object can emerge when you call a method, a particular method might produce any number of different types of exceptions, all of which need descriptions. So the form for the exception tag is:
@throws fully-qualified-class-name description
in which fully-qualified-class-name gives an unambiguous name of an exception class that’s defined somewhere, and description (which can continue on subsequent lines) tells you why this particular type of exception can emerge from the method call. Feedback
@deprecated
This is used to indicate features that were superseded by an improved feature. The deprecated tag is a suggestion that you no longer use this particular feature, since sometime in the future it is likely to be removed. A method that is marked @deprecated causes the compiler to issue a warning if it is used. Feedback
Documentation example
Here is the first Java program again, this time with documentation comments added:
//: c02:HelloDate.java
import java.util.*;
/** The first Thinking in Java example program.
* Displays a string and today's date.
* @author Bruce Eckel
* @author www.BruceEckel.com
* @version 2.0
*/
public class HelloDate {
/** Sole entry point to class & application
* @param args array of string arguments
* @return No return value
* @exception exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it's: ");
System.out.println(new Date());
}
} ///:~