How to Write Doc Comments for Javadoc

How to Write
Doc Comments for Javadoc

(under construction)

Formatting and Content Conventions
Descriptions, Tags and a Blank Line
Descriptions
Tag Conventions
Including Images
Examples of Doc Comments
Troubleshooting Curly Quotes (Microsoft Word)

Formatting and Content Conventions

This document describes the formatting and content conventions we use in doc comments at JavaSoft.

Terminology

API documentation (API docs) or API specifications (API specs)
On-line or hardcopy descriptions of the API, intended primarily for programmers writing in Java. Thes can be generated using the javadoc tool or created some other way. Examples would be the on-line JDK API docs and the Chan/Lee Java Class Libraries book.
Documentation comments (doc comments)
The special comments in the Java source code that are delimited by the /** ... */ tags. These comments are processed by the Javadoc tool to generate the API Docs.
javadoc
The JDK tool that generates API documentation from documentation comments.

Who "Owns" the Doc Comments
In general, the doc comments are not owned exclusively by writers or programmers, but their ownership is shared between them. It is a basic premise that writers and programmers honor each other's capabilities and both contribute to the best doc comments possible.

It is very much common practice for a programmer to write the initial doc comments, using sparse language, omitting many of the tags, and for the writer to go back and refine the content, adding tags.

With that in mind, these guidelines are intended to describe the end-product. They are intended only as suggestions for programmers, not requirements. Any of these guidelines that programmers happen to follow would be great, but it is not intended that they should in any way to add to programmer's burden. (This note shall henceforth be known as "Kramer's Caveat". In other words, don't push this spec on developers! :)

Descriptions, Tags, and Blank Lines

A doc comment is made up of two parts -- a description followed by zero or more tags, with a blank line (containing a single asterisk "*") between these two sections:
    /** 
     * This is the description part of a doc comment
     *
     * @tag    Comment for the tag
     */
The first line is indented to line up with the code below the comment, and starts with the begin-comment symbol (/**) followed by a return.

Subsequent lines start with an asterisk *. They are indented an additional space so the asterisks line up. A space separates the asterisk from the descriptive text or tag that follows it.

Insert a blank comment line between the description and the list of tags, as shown.

Insert additional blank lines to create "blocks" of related tags (discussed in greater detail below).

The last line begins with the end-comment symbol (*/) indented so the asterisks line up and followed by a return. Note that the end-comment symbol contains only a single asterisk (*).

Break any doc-comment lines exceeding 80 characters in length, if possible. If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag.
Also see Troubleshooting Curly Quotes (Microsoft Word) at the end of this document.

Descriptions

First Sentence
The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). For example, this first sentence ends at "Prof.":
   /**
    * This is a simulation of Prof. Knuth's MIX computer.
    */
However, you can work around this by typing an HTML meta-character such as "&" or "<" immediately after the period, such as:
   /**
    * This is a simulation of Prof.&nbsp;Knuth's MIX computer.
    */
or
   /**
    * This is a simulation of Prof. Knuth's MIX computer.
    */
Javadoc copies this first sentence to the member summary at the top of the web page, so it is important to write crisp and informative initial sentences. In particular, write summary sentences that distinguish overloaded methods from each other. For example:
   /** 
    * Class constructor.
    */
   foo() {
     ...
/**
* Class constructor specifying number of objects to create.
*/
foo(int n) {
...
Use of <code> Style
Keywords and API names are offset by <code>...</code> when mentioned in a description. This includes:

Java keywords
package names
class names
method names
interface names
variable names
argument names
code examples

Use of Parentheses for Method and Constructor Names
Method and constructor names specified in a description are offset by <code>...</code>. Parentheses are not used except to denote a particular signature.

So we generally say <code>getLabel</code> and not "getLabel()". We only use <code>getLabel()</code> if we are talking specifically about the zero-argument method or constructor.

Writing Documentation Comments: A Style Guide
Okay to use phrases instead of complete sentences, in the interests of brevity. This holds especially in the initial summary and in @param tag descriptions.

Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person imperative.

Gets the label. (preferred)

Get the label. (avoid)

Method descriptions begin with a verb phrase.
A method implements an operation, so it usually starts with a verb phrase:

Gets the label of this button. (preferred)

This method gets the label of this button. (avoid)

Class/interface/field descriptions can omit the subject and simply state the object. These API often describe things rather than actions or behaviors:

A button label. (preferred)

This field is a button label. (avoid)

Use "this" instead of "the" when referring to an object created from the current class. For example, the description of the getToolkit method should read as follows:

Gets the toolkit for this component. (preferred)

Gets the toolkit for the component. (avoid)
Add description beyond the API name. The best API names are "self-documenting", meaning they tell you basically what the API does. If the doc comment merely repeats the API name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name.

Avoid - The description below says nothing beyond what you know from reading the method name. The words "set", "tool", "tip", and "text" are simply repeated in a sentence.
    /**
     * Sets the tool tip text.
     *
     * @param text  The text of the tool tip.
     */
    public void setToolTipText(String text) {
Preferred - This description more completely defines what a tool tip is, in the larger context of registering and being displayed in response to the cursor.
    /**
     * Registers the text to display in a tool tip.   The text 
     * displays when the cursor lingers over the component.
     *
     * @param text  The string to display.  If the text is null, 
     *              the tool tip is turned off for this component.
     */
    public void setToolTipText(String text) {
Be clear when using the term "field". Be aware that the word "field" has two meanings:

static field, which is another term for "class variable"
text field, as in the TextField class. Note that this kind of field might be restricted to holding dates, numbers or any text. Alternate names might be "date field" or "number field", as appropriate.

Avoid Latin -- spell out "aka" (also known as), use "that is" instead of "i.e.", use "for example" instead of "e.g", and use "to be specific" or "in other words" instead of "viz."

Tag Conventions

Most of the following tags are specified in the Java Language Specification. Also see the javadoc reference page.
Order of Tags
Include tags in the following order:
* @author       (classes and interfaces only, required)
* @version      (classes and interfaces only, required) (see footnote 1)
*               
* @param        (methods only)
* @return       (methods only - will eventually become @returns)
* @exception    (will eventually become @throws)
*               
* @see          
* @since        
* @deprecated   (see How and When To Deprecate APIs)
Tag Blocks
For readability, divide the tags into blocks of related tags. The blocks shown above are an example.
Ordering Multiple Tags
Multiple @author tags should be listed in chronological order. The creator of the class should be listed at the top.
Multiple @param tags should be listed in argument-declaration order.

Multiple @exception tags should be listed alphabetically by the arguments (exception names). Multiple @exception tags can be divided divided into a separate block. A single @exception tag can be "tacked on" to the @param / @return block.
Similarly, multiple @see tags should be ordered alphabetically and organized into a separate block. A single @see tag can be "tacked on" to the tags below it.

Required Tags
An @param tag is required for every parameter, even when the description is obvious. The @return tag is required for every method that returns something other than void, even if it is redundant with the method description. (Whenever possible, find something non-redundant (ideally, more specific) to use for the tag comment.)

These principles expedite automated searches and automated processing. Frequently, too, the effort to avoid redundancy pays off in extra clarity.

Tag Comments
Use the following guidelines to create comments for each tag:
@author
If the author is unknown, use "unascribed" as the argument to @author.

@version
The JavaSoft convention for the argument to the @version tag is the SCCS string "%I%, %G%", which converts to something like "1.39, 02/28/97" when the file is checked out of SCCS.

@param
The @param tag is followed by the name (not type) of the parameter, followed by a description of the parameter. The first non-trivial word in the description is the data type of the parameter. (Trivial words are articles like "a", "an", and "the".) Additional spaces can be inserted between the name and description so that comments line up in a block. Dashes or other punctuation should not be inserted before the description. (JavaDoc provides hyphens automatically).

The name and data type always start with a lowercase letter. The description is most usually a phrase, starting with a lowercase letter and ending without a period, unless it contains a complete sentence.

Example:
@param ch        the character to be tested
@param observer  the object to be notified
Do not bracket the name of the parameter after the @param tag with <code>...<code>. (The Javadoc tool may do that automatically at some point.)

When writing the comments themselves:

Prefer a phrase to a sentence.

Giving a phrase, do not capitalize, do not end with a period.
@param x a phrase goes here

Giving a sentence, capitalize it and end it with a period.
@param x This is a sentence.

Givng multiple sentences, follow all sentence rules.
@param x This is sentence #1. This is sentence #2.

Giving multuple phrases, separate with a semi-colon and a space.
@param x phrase #1 here; phrase #2 here

Giving a phrase followed by a sentence, do not capitalize the phrase. However, end it with a period to distinguish the start of the next sentence.
@param x a phrase goes here. This is a sentence.
@return
Omit @return for methods that return void; include it for all other methods and constructors, even if its content is entirely redundant with the method description. Having an explicit @return tag makes it easier for someone to find the return value quickly. Whenever possible, supply more detailed information (such as returning -1 when an out-of-bounds argument is supplied).

@deprecated
The @deprecated description should tell the user how to avoid using the class or method and explain why it has been deprecated. An @see tag should be included that points to the replacement method. The standard format is, for example:
  /**
   * @deprecated  Replaced by setBounds
   * @see #setBounds(int,int,int,int)
   */
If the member is obsolete and there is no replacement, the argument to @deprecated should be "No replacement".

Incorrectly specified @deprecated tags should be fixed wherever they are found, because Javadoc parses the entire paragraph following the @deprecated tag and moves it to the front of the description, placing it in italics and preceding it with a bold warning: "Note: foo is deprecated". (It also adds "Deprecated" in bold to any index entries mentioning the deprecated entity.)

Do not add @deprecated tags without first checking with the appropriate engineer. Substantive modifications should likewise be checked first.
@exception
An @exception tag should be included for at least any declared (checked) exceptions, as illustrated below. It can also document any non-declared exceptions that can be thrown by the method, normally those that appear directly in the implementation, rather than those that are indirectly thrown.
  /**
   * @exception IOException  If an IO error occurred
   */
  public void f() throws IOException {
      // body
  }

Including Images

This section covers images used in the doc comments, not images directly used by the source code.

NOTE: The bullet and heading images required with Javadoc version 1.0 and 1.1 are located in the images directory of the JDK download bundle: jdk1.2/docs/api/images/

Javadoc is not yet smart enough to copy over images (GIF, JPEG, etc) to the destination directory. You must copy them manually until we add that feature in Javaodoc 1.2.

The following are the JavaSoft proposals for conventions for including images in doc comments; Javadoc does not yet support any of these. The master images would be located in the source tree; when javadoc is run with the standard doclet, it would copy those files to the destination HTML directory. Please send comments to javadoc@sun.com

Images in Source Tree

Naming of doc images in source tree - Name GIF images "<class>-1.gif", incrementing the integer for subsequent images in the same class. Example: Button-1.gif

Location of doc images in source tree - Put doc images in a directory called "doc-files". This directory should reside in the same package directory where the source files reside. The name "doc-files" distinguishes it as documentation separate from images used by the source code itself, such as bitmaps displayed in the GUI. Example: A screen shot of a button, Button-1.gif, might be included in the class comment for the Button class. The Button source file and the image would be located at:

java/awt/Button.java (source file)

java/awt/doc-files/Button-1.gif (image file)

Images in HTML Destination
Naming of doc images in HTML destination - Images would have the same name as they have in the source tree. Example: Button-1.gif
Location of doc images in HTML destination -
With flat file output, directories would be located in the package directory and named "images-<package>". For example:
  api/images-java.awt/
  api/images-java.awt.swing/
With hierarchical file output, directories would be located in the package directory named "doc-files". For example:
  api/java/awt/doc-files/Button-1.gif

Examples of Doc Comments

/**
 * Graphics is the abstract base class for all graphics contexts
 * which allow an application to draw onto components realized on
 * various devices or onto off-screen images.
 * A Graphics object encapsulates the state information needed
 * for the various rendering operations that Java supports.  This
 * state information includes:
 * <ul>
 * <li>The Component to draw on
 * <li>A translation origin for rendering and clipping coordinates
 * <li>The current clip
 * <li>The current color
 * <li>The current font
 * <li>The current logical pixel operation function (XOR or Paint)
 * <li>The current XOR alternation color
 *     (see <a href="#setXORMode">setXORMode</a>)
 * </ul>
 * <p>
 * Coordinates are infinitely thin and lie between the pixels of the
 * output device.
 * Operations which draw the outline of a figure operate by traversing
 * along the infinitely thin path with a pixel-sized pen that hangs
 * down and to the right of the anchor point on the path.
 * Operations which fill a figure operate by filling the interior
 * of the infinitely thin path.
 * Operations which render horizontal text render the ascending
 * portion of the characters entirely above the baseline coordinate.
 * <p>
 * Some important points to consider are that drawing a figure that
 * covers a given rectangle will occupy one extra row of pixels on
 * the right and bottom edges compared to filling a figure that is
 * bounded by that same rectangle.
 * Also, drawing a horizontal line along the same y coordinate as
 * the baseline of a line of text will draw the line entirely below
 * the text except for any descenders.
 * Both of these properties are due to the pen hanging down and to
 * the right from the path that it traverses.
 * <p>
 * All coordinates which appear as arguments to the methods of this
 * Graphics object are considered relative to the translation origin
 * of this Graphics object prior to the invocation of the method.
 * All rendering operations modify only pixels which lie within the
 * area bounded by both the current clip of the graphics context
 * and the extents of the Component used to create the Graphics object.
 * 
 * @version 	%I%, %G%
 * @author 	Sami Shaio
 * @author 	Arthur van Hoff
 * @since       JDK1.0
 */
public abstract class Graphics {

    /** 
     * Draws as much of the specified image as is currently available at
     * the specified coordinate (x, y).
     * This method will return immediately in all cases, even if the
     * entire image has not yet been scaled, dithered and converted
     * for the current output device.
     * If the current output representation is not yet complete then
     * the method will return false and the indicated ImageObserver
     * object will be notified as the conversion process progresses.
     *
     * @param img       the image to be drawn
     * @param x         the x coordinate
     * @param y         the y coordinate
     * @param observer  the object to be notified as more of the image is
     *                  converted
     * @return          <code>true</code> if the image is completely 
     *                  loaded and was painted successfully; 
     *                  <code>false</code> otherwise.
     * @see             Image
     * @see             ImageObserver
     * @since           JDK1.0
     */
    public abstract boolean drawImage(Image img, int x, int y, 
				      ImageObserver observer);


    /**
     * Dispose of the system resources used by this graphics context.
     * The Graphics context cannot be used after being disposed of.
     * While the finalization process of the garbage collector will
     * also dispose of the same system resources, due to the number
     * of Graphics objects that can be created in short time frames
     * it is preferable to manually free the associated resources
     * using this method rather than to rely on a finalization
     * process which may not happen for a long period of time.
     * <p>
     * Graphics objects which are provided as arguments to the paint
     * and update methods of Components are automatically disposed
     * by the system when those methods return.  Programmers should,
     * for efficiency, call the dispose method when finished using
     * a Graphics object only if it was created directly from a
     * Component or another Graphics object.
     *
     * @see       #finalize
     * @see       Component#paint
     * @see       Component#update
     * @see       Component#getGraphics
     * @see       #create
     * @since     JDK1.0
     */
    public abstract void dispose();

    /**
     * Disposes of this graphics context once it is no longer referenced.
     * @see       #dispose
     * @since     JDK1.0
     */
    public void finalize() {
	dispose();
    }
}

Troubleshooting Curly Quotes (Microsoft Word)

Problem - A problem occurs if you are working in an editor that defaults to curly (rather than straight) single and double quotes, such as Microsoft Word on a PC -- the quotes disappear when displayed in some browers (such as Unix Netscape). So a phrase like "the display's characteristics" becomes "the displays characteristics."

The illegal characters are the following:

146 - right single quote
147 - left double quote
148 - right double quote

What should be used instead is:

39 - straight single quote
34 - straight quote

Preventive Solution - The reason the "illegal" quotes occurred was that a default Word option is "Change 'Straight Quotes' to 'Smart Quotes'". If you turn this off, you get the appropriate straight quotes when you type.
Fixing the Curly Quotes - Microsoft Word has several save options -- use "Save As Text Only" to change the quotes back to straight quotes. Be sure to use the correct option:

"Save As Text Only With Line Breaks" - inserts a space at the end of each line, and keeps curly quotes.
"Save As Text Only" - does not insert a space at the end of each lines, and changes curly quotes to straight quotes.

Footnotes

[1] At JavaSoft, we use @version for the SCCS version. See "man sccs-get" for details. The concensus seems to be:

As Rachel explained to me, when you create a file, %I% is set to 1.1. When you edit and delget it, it increments to 1.2.

Some developers omit the date %G% (and have been doing so) if they find it too confusing (3/4/96 is ambiguous to Europeans), and include the time %U% if they want more resolution (multiple delgets in a day).

The real solution would be to have the date formatted as text (10 Oct 1996 or Oct 10 1996), as Rich suggested, but that's an enhancement for SCCS.

[Author's comment: Include more comments from step 5 of:
~dkramer/javadocdir/moving-frame-into-src.html#revisproc
"Manual edit the HTML files produced by WebWorks"]

rogerp91 / comments-javadoc