How to Write Javadoc Comments

Format of a Doc Comment

A doc comment is written in HTML and must precede a class, field, constructor or method declaration. It is made up of two parts -- a description followed by block tags. In this example, the block tags are @param, @return, and @see.

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }
                        

• The resulting HTML from running Javadoc is shown below
• Each line above is indented to align with the code below the comment.
• The first line contains the begin-comment delimiter ( /**).
• Starting with Javadoc 1.4, the leading asterisks are optional.
• Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
• Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
• If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag, as shown.
• Insert a blank comment line between the description and the list of tags, as shown.
• The first line that begins with an "@" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
• The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.

For more examples, see Simple Examples.

So lines won't wrap, limit any doc-comment lines to 80 characters.

Here is what the previous example would look like after running the Javadoc tool:

getImage

public Image getImage(URL url,
             String name)

Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument.

This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Parameters:

url - an absolute URL giving the base location of the image.

name - the location of the image, relative to the url argument.

Returns:

the image at the specified URL.

See Also:

Image

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 item. This means the first sentence of each member, class, interface or package description. The Javadoc tool copies this first sentence to the appropriate member, class/interface or package summary. This makes it important to write crisp and informative initial sentences that can stand on their own.

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. Knuth's MIX computer.
    */

or

   /**
    * This is a simulation of Prof.<!-- --> Knuth's MIX computer.
    */

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.

• Ideally, make it complete enough for conforming implementors. Realistically, include enough description so that someone reading the source code can write a substantial suite of conformance tests. Basically, the spec should be complete, including boundary conditions, parameter ranges and corner cases.

• Where appropriate, mention what the specification leaves unspecified or allows to vary among 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 Windows systems, the path search behavior of the loadLibrary method is identical to that of the Windows API's LoadLibrary procedure.

  The use of "On Windows" 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 the Javadoc tool 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, The Javadoc tool 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, the Javadoc tool 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, the Javadoc tool 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

• 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)

• OK 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.

• 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
  use "also known as" instead of "aka", use "that is" or "to be specific" instead of "i.e.", use "for example" instead of "e.g.", and use "in other words" or "namely" instead of "viz."

Excerpted from the original.