Guidelines for writing
Javadoc documentation comments

Maintained by Reinhold Plösch and Rainer Weinreich

Version 1.1P
8.3.2000

This document describes the formatting and content conventions we use in documentation comments for Java programs. It concentrates on conventions that should be adhered to. The document is an adapted version of Sun's "How to Write Doc Comments for Javadoc" document.

Types of Source Files
Copyright information
General Form of a Doc Comment
Descriptions
A Style Guide
Tag Conventions

Types of Source Files

Javadoc can generate output originating from four different types of "source" files:

Source code files for Java classes (.java) - these contain class, interface, field, constructor and method comments.

Package comment files - these contain package comments

Overview comment files - these contain comments about the set of packages

Miscellaneous unprocessed files - these include images, sample source code, class files, applets, HTML files, and whatever else you might want to referenced from the previous files.

Copyright Information

Every java source code file must contain a copyright information at the top of the file, i.e., before the package statement or (in case of absence) the import statement. The first line of the copyright information contains the name of the source code file. The version number as well as the date of last change (as preferred by Sun Micrososystems) need not be included.
    /* 
     * @(#)Table.java
     *
     * Copyright 2000 by <Name of person and/or organization>,  
     * All rights reserved.
     */

General Form of a Doc Comment

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.

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) {
     ...
Implementation-Independence
Write the description to be implementation-independent, but specifying such dependencies where necessary. This helps engineers write code to be "write once, run anywhere."

As much as possible, write doc comments as an implementation-independent API specification.

Define clearly what is required and what is allowed to vary across platforms/implementations.

If you must document implementation-specific behavior, please document it in a separate paragraph with a lead-in phrase that makes it clear it is implementation-specific. If the implementation varies according to platform, then specify "On <platform>" at the start of the paragraph. In other cases that might vary with implementations on a platform you might use the lead-in phrase "Implementation-Specific:". Here is an example of an implementation-dependent part of the specification for java.lang.Runtime:

On Win32 systems, the path search behavior of the loadLibrary method is identical to that of the Win32 API's LoadLibrary procedure.

The use of "On Win32" at the beginning of the sentence makes it clear up front that this is an implementation note.

Automatic re-use of method comments
You can avoid re-typing doc comments by being aware of how Javadoc duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases:

When a method in a class overrides a method in a superclass

When a method in an interface overrides a method in a superinterface

When a method in a class implements a method in an interface

In the first two cases, if a method m() overrides another method, Javadoc will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.

In the third case, if a method m() in a given class implements a method in an interface, Javadoc will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.

In all three of these cases, if the method m() contains no doc comments or tags, Javadoc will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m(). If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.

A Style Guide

The following are useful tips and conventions for writing descriptions in doc comments.

Use <code> style for keywords and names.
Keywords and names are offset by <code>...</code> when mentioned in a description. This includes:
- Java keywords
- package names
- class names
- method names
- interface names
- field names
- argument names
- code examples
Use in-line links economically
You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:
- The user might actually want to click on it for more information (in your judgment), and
- Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)
Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known.

Omit parentheses for the general form of methods and constructors
When referring to a method or constructor that has multiple forms, and you mean to refer to a specific form, use parentheses and argument types. For example, ArrayList has two add methods: add(Object) and add(int, Object).

The add(int, Object) method adds an item at a specified position in this arraylist.

However, if referring to both forms of the method, omit the parentheses altogether. It is misleading to include empty parentheses, because that would imply a particular form of the method. The intent here is to distinguish the general method from any of its particular forms. Include the word "method" to distinguish it as a method and not a field.

The `add` method enables you to insert items.	(preferred)
The `add()` method enables you to insert items.	(avoid when you mean "all forms" of the add method)

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.

Returns the label. (preferred)

Return the label. (avoid)

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

Returns the label of this button.	(preferred)
This method returns 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:

Returns the toolkit for this component.	(preferred)
Returns 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)
*               
* @param        (methods and constructors only)
* @return       (methods only)
* @exception    (@throws is a synonym added in Javadoc 1.2)
* @see          
* @spec		(classes only)
* @deprecated   
*
* @knownBugs    (classes, interfaces and methods only)
*
* @history      (classes and interfaces only)
Tag Blocks
For readability, divide the tags into blocks of related tags. The blocks shown above are an example.

Ordering Multiple Tags
We employ the following conventions when a tag appears more than once in a documentation comment. If desired, groups of tags, such as multiple @see tags, can be separated from the other tags by a blank line with a single asterisk.

Multiple @param tags should be listed in argument-declaration order. This makes it easier to match the list to the signature with your eyes.

Multiple @exception tags (also known as @throws) should be listed alphabetically by the exception names.

Multiple @see tags should be ordered as follows, which is roughly the same order as their arguments are searched for by javadoc, basically from nearest to farthest access, from least-qualified to fully-qualified, The following list shows this progression. Notice the methods and constructors are in "telescoping" order, which means the "no arg" form first, then the "1 arg" form, then the "2 arg" form, and so forth. Where a second sorting key is needed, they could be listed either alphabetically or grouped logically.
   @see #field
   @see #Constructor(Type, Type...)
   @see #Constructor(Type id, Type id...)
   @see #method(Type, Type,...)
   @see #method(Type id, Type, id...)
   @see Class
   @see Class#field
   @see Class#Constructor(Type, Type...)
   @see Class#Constructor(Type id, Type id)
   @see Class#method(Type, Type,...)
   @see Class#method(Type id, Type id,...)
   @see package.Class
   @see package.Class#field
   @see package.Class#Constructor(Type, Type...)
   @see package.Class#Constructor(Type id, Type id)
   @see package.Class#method(Type, Type,...)
   @see package.Class#method(Type id, Type, id)
   @see package
Required Tags
An @param tag is required for every paramete. It may be omitted in very obvious cases. The @return tag is required for every method that returns something other than void. It may be omited in very obvious cases.

Tag Comments
As a reminder, the fundamental use of these tags is described on the Javadoc Reference page. Java Software generally uses the following additional guidelines to create comments for each tag:
@author (reference page)

An author is a person that has major responsibility for a class. There may be multiple authors for a class. Authors making contributions and enhancements to a class are listed with the @history tag.

@version (reference page)

The version number is maintained manually. The initial version number to be used for documentation of the RSE Software is 1.0.

@param (reference page)
The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as Javadoc inserts one dash.
Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class. The description is most usually a phrase, starting with a lowercase letter and ending without a period, unless it contains a complete sentence or is followed by another sentence (as described further below).

Example:
  * @param ch        the character to be tested
  * @param observer  the image observer to be notified 
Do not bracket the name of the parameter after the @param tag with <code>...</code> since Javadoc 1.2 automatically does this. (Javadoc will do the right thing and will not insert code tags around the parameter name if they are already present.)

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.

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

Giving multiple 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 (reference page)

Omit @return for methods that return void and for constructors; include it for all other methods, 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 return values for special cases (such as specifying the value returned when an out-of-bounds argument is supplied).

@exception (@throws is a synonym added in Javadoc 1.2) (reference page)

An @exception tag should be included for any checked exceptions (declared in the throws clause), as illustrated below, and also for any unchecked exceptions that the caller might reasonably want to catch, with the exception of NullPointerException. Errors should not be documented as they are unpredictable.
  /**
   * @exception IOException  If an input or output exception occurred
   */
  public void f() throws IOException {
      // body
  }
@spec (This is not a standard java documentation tag)

Allows to place hints to the written specification. In most cases it will be sufficient to place the appropriate section number(s) of the written software requirements specification here. More text may be added.

@deprecated (reference page)

The @deprecated description in the first sentence should at least tell the user when the API was deprecated and what to use as a replacement. Only the first sentence will appear in the summary section and index. Subsequent sentences can also explain why it has been deprecated. When generating the description for a deprecated API, Javadoc moves the @deprecated text ahead of the description, placing it in italics and preceding it with a bold warning: "Deprecated". An @see tag (for Javadoc 1.1) or {@link} tag (for Javadoc 1.2 or later) should be included that points to the replacement method. If the member has no replacement, the argument to @deprecated should be "No replacement".

@knownbugs (This is not a standard java documentation tag)

Describes a known bug with the class or member function. One tag per bug should be used.

@history (This is not a standard java documentation tag)

Describes how a class has been modified over time. For each change, the description should include: who made it, when it was made, what was done, why it was done, and a reference to the change request and/or user requirement that resulted in it. Minor bug fixes should not be included here.
Example:
  * @history 27.8.1999 Rainer Weinreich
  *          Method <code>public AgentDesc getAgentDesc()</code>inserted,as
  *          access is needed by several report agents.
  * @history 20.8.1999 Reinhold Plösch
  *          All instance variables of type jave.util.Vector changed to
  *          appropriate Java2-style collection classes.
{@link} (Added in Javadoc 1.2) (reference page)

For conventions, see Use In-Line Links Economically.

A button label.	(preferred)
This field is a button label.	(avoid)

Guidelines for writing Javadoc documentation comments