Javadoc Notes, Version 1

collected from Sun's documentation

Contents

Introduction

This document is a brief introduction to the proper use of javadoc comments in Java source code. The proper and consistent use of these allows for the easy maintenance of accurate Java project documentation. The javadoc tool processes files that end in ".java", plus these other files: package comment files, overview comment file, miscellaneous unprocessed files, and test files and template files.

Java Source Files

All source documentation blocks have this basic format:

/**
 * Sample documentation comment.  It is a longer comment that 
 * spans more than one line.  If you don't need this much space then
 * you can use the second method (listed right below this one).
 */
 
/** A really short comment all on one line. */

For source documentation to be recognized by the javadoc processor, these comment blocks must be located immediately before the class, interface, contructor, method, or field declaration. All documentation comments have an optional main description followed by an optional tag section. There are two types of tags, block (or standalone) tags, which look like this: @tag, and in-line tags, which look like this: {@tag}. Inline tags are allowed anywhere that text is allowed. Here is an example of both:

/**
 * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
 */

Avoid using html header tags (<h1>, etc.) except in class and package documentation.

Class and Interface Tags
Field Documentation Tags
Constructor and Method Documentation Tags

Package Comment Files

Each package can have its own documentation comment. The file must be named package.html and must be located in the same directory as the Java source files for that package. The contents of this file is one big documentation comment, with one exception. You must omit the comment separators /** and */, plus all leading *.

This should be a standard html file. The very first sentence in the <body> tag should be the package summary. You may then use any of the following tags:

Overview Comment File

Each application or set of packages can have its own overview documentation comment. Name the file overview.html and place it at the top level of the source tree.

Use the same layout as for the package comment file. That is, use a standard html file format. The first sentence after the <body> tag should be a summary of the overview. Do not put a title or any other text between the <body> tag and the summary sentence. Here are the tags that be used:

Miscellaneous Unprocessed Files

These are things like graphic files, example java source, and other related html files. To use these types of files, create a directory called doc-files, which can be a sub-directory of any package directory. If you link to any files in these directories you must hard-code the links in your "regular" javadoc files. For example:

/**
 * This button looks like this:
 * <img src="doc-files/button.gif" />
 */

Test Files and Template Files

If you want to include various test and template files in the same directory tree with your regular project source files, but ensure that the javadoc processor doesn't try to process them, you need to follow these conventions.

Test Files

These are valid java source files, but may or may not be in the same package as the files they are intended to be used with. Create a sub-directory in your package directory called test-files. The javadoc processor will ignore them.

Template Files

These are java template files which do not contain all valid java source and are intended to be used as a convenience to the programmer. they can be placed in the same directory as your package source code. Just give them a name with a "-" in it. This makes them have an invalid name for a Java source code file and so the javadoc processor will ignore them. For example: Class-Template.java.

Javadoc Tags

@author name-text
Can specify multiple authors per tag or have multiple @author tags with one name per tag.
@deprecated deprecated-text
Add a comment that this API should no longer be used, even though it may continue to work for now.
{@docRoot}
Generates a path to the root of the generated documentation's root directory. Useful for including things like copyright files or logos, etc. For example: See the <a href="{@docRoot}/copyright.html">Copyright</a>.
@exception class-name description
This is a synonym for @throws.
{@inheritDoc}
Copies the documentation from the "nearest" inheritable class or implementable interface into the current documentation comment at this tag's location. It is valid only in the main description block of a method, or in the text arguments of the @return, @param, and @throws.
Inserts an inline link that displays label
{@linkplain package.class#member label}
Same as {@link} tag except that the link text is displayed in plain rather than code text font.
@param parameter-name description
Documents a method parameter. May be continued over multiple lines.
@return description
Describes the return type and permissible range of values.
@see reference
Add a "See Also" heading with a link or text entry that points to reference. You can code this three different ways. The first way @see "string" doesn't generate a link. The next way @see <a href="URL#value">label</a> adds the appropriate link. And the last and most comment way is @see package.class#member label. Note that label can be omitted and javadoc will insert something appropriate.
@serial field-description | include | exclude
Used for a default serializable field. The include or exclude arguments identify whether a class or package should be included or excluded from the serialized form page. If a serializable field is added to a class some time after the class was first made serializable, a statement should be added to the main description to identify at which version it was added.
@serialField field-name field-type field-description
Documents an ObjectStreamField component of a Serializable class's serialPersistenFields member. One tag for each ObjectStreamField component.
@serialData data-description
Documents the types and order of data in the serialized form. Can be used for the writeObject, readObject, writeExternal, and readExternal methods.
@since since-text
Adds a "Since" heading with the specified since-text. You can have multiple @since tags.
@throws class-name description
Adds a "Throws" heading with the specified info.
{@value}
When used when documenting a static field it will display the value of the constant on the Constant Field Values page.
@version version-text
Adds a "Version" subheading wiht the specified version-text.