![[Home]](../images/home.jpg){kind=small}
Here is a link to a Javadoc Tutorial.
/**
* This is a document comment.
*/
class Demo
{
private int x; // This is a single line comment.
/*
This is a multiple line comment.
Another line.
*/
} // Demo
As expected, all of the comment types are used to document the code without introducing syntax errors. However, the document comments goes a step further by allowing the creation of separate documentation via the use of the javadoc tool. The javadoc tool allows the user to create API documentation in the form of HTML pages. The documentation information is gathered directly from the source code and the document comments.
As stated before, a document comment begins with /** and ends with */. Each line within the comment must start with a *. While you can leave out the leading *, you run the risk of loosing any indentation that you may have placed within the comment. Consequently, it is advisable that you start each line with the asterisk, *.
The first sentence should consist of a summary of the purpose of the entity in question i.e. a class, an interface, a constructor, a method or a field. It should be both concise and informative. One should try to fit the sentence on a single line but you can go onto the next line since the javadoc tool considers the end of the summary sentence to be the first period (followed by a blank, tab, newline or tag) that it encounters. Note that you can follow the line with further sentences. The first occurrence of a tag indicates the end of the description.
You can also embed HTML tags within the document comments. However, if you need to include <, > or & in the description, then you should use < and > and &.
The javadoc tool will only recognise a document comment if it appears immediately before class, interface, constructor, method or field declarations. Also you can only have one comment per declaration.
The following example gives a document comment for a class with embedded HTML.
/**
* This is a <i>document</i> comment.
*/
class Demo
{
} // Demo
Some of the currently available tags are given below. For more information go to the Java web site while for proposed tags, go to the Proposed Tags web site.
The current tags are:
|
|
|
|
| @author name | 1.0 | You can add multiple @author tags to a document comment. Each tag can contain a single name or more than one name. If there are multiple names then separate them with commas. An author section is only added to the documentation when the -author option is used with the javadoc tool. |
| @exception class-name description | 1.0 | This tag is the same as the @throws tag. |
| @param parameter-name description | 1.0 | This should describe the purpose of the parameter and its possible values. You can continue the description on the next line if required. The use of this tag adds a parameter section to the documentation. |
| @return description | 1.0 | Describes the return type and the range of possible values. The use of this tag adds a return section to the generated documentation. |
| @see reference-name | 1.0 | This is usually the name of a class within your API that is being used by the current class. The javadoc tool will create a link to the relevant documentation if available. This is a fairly complex tag and so you should consult the javadoc documentation. |
| @throws class-name description | 1.2 | This adds a Throws subheading to the generated documentation. Note that class-name is the name of the exception class that can be thrown. |
| @version version | 1.0 | Generally contains the version number of the current class. It has no special format and is used in conjunction with the javadoc -version option. This tag can only be used once in a document comment. |
For further information go to the Java web site.