Document a package using Javadoc - Real's Java How-to

Since JDK 1.5, to create a package comment file, you have a choice of two files to place your comments:

• package-info.java - Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is new in JDK 5.0, and is preferred over package.html.
• package.html - Can contain only package comments and Javadoc tags, no package annotations.

See http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment

Required Tags
An @param tag is "required" (by convention) for every parameter,even when the description isobvious. The @return tag is required for every method that returns somethingother than void, even if it is redundant with the method description.(Whenever possible, find something non-redundant (ideally, more specific) to usefor 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
As a reminder, the fundamental use of these tags is describedon the JavadocReference page. Java Software generally uses the following additionalguidelines to create comments for each tag:

@author    (reference page)

You can provide one @author tag, multiple @author tags, or no @authortags. In these days of the community process when developmentof new APIs is an open, joint effort, the JSR can be consider theauthor for new packages at the package level. For example, the newpackage java.nio has "@author JSR-51 Expert Group" at thepackage level. Then individual programmers can be assignedto @author at the class level. As this tag can only be appliedat the overview, package and class level, the tag applies only tothose who make significant contributions to the design orimplementation, and so would not ordinarily include technical writers.

The @author tag is not critical, because it is not included whengenerating the API specification, and so it is seen only by thoseviewing the source code. (Version history can also be used fordetermining contributors for internal purposes.)

If someone felt strongly they need to add @author at the memberlevel, they could do so by running javadoc using the new 1.4-tag option:

    -tag author:a:"Author:"

If the author is unknown, use "unascribed" as the argument to@author.Also see order of multiple @author tags.

@version    (reference page)

The Java Software convention for the argument to the @version tag is theSCCS string "%I%, %G%", which converts to something like "1.39, 02/28/97"(mm/dd/yy) when the file is checked out of SCCS.

@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 nounin the description is the data type of the parameter. (Articles like"a", "an", and "the" can precede the noun.) An exception is madefor the primitive int, where the data type is usually omitted.Additional spaces can be inserted between the name and descriptionso that the descriptions line up in a block. Dashes or other punctuationshould not be inserted before the description, as the Javadoc tool insertsone dash.

Parameter names are lowercase by convention.The data type starts with a lowercase letter to indicatean object rather than a class. The description begins with alowercase letter if it is a phrase (contains no verb), or anuppercase letter if it is a sentence. End the phrase with aperiod only if another phrase or sentence follows it.

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... since Javadoc 1.2 andlater automatically do this. (Beginning with 1.4, the namecannot contain any HTML, as Javadoc compares the @param nameto the name that appears in the signature and emits a warningif there is any difference.)

When writing the comments themselves, in general, start witha phrase and follow it with sentences if they are needed.

• When writing a phrase, do not capitalize and do not end with a period:
    @param x  the x-coordinate, measured in pixels

• When writing a phrase followed by a sentence, do not capitalize the phrase, but end it with a period to distinguish it from the start of the next sentence:
    @param x  the x-coordinate. Measured in pixels.

• If you prefer starting with a sentence, capitalize it and end it with a period:
    @param x  Specifies the x-coordinate, measured in pixels.

• When writing multiple sentences, follow normal sentence rules:
    @param x  Specifies the x-coordinate. Measured in pixels.

Also see order of multiple @param tags.

@return    (reference page)

Omit @return for methods that return void and for constructors; include itfor all other methods, even if its content is entirely redundant with themethod description. Having an explicit @return tag makes it easier forsomeone to find the return value quickly. Whenever possible, supply returnvalues for special cases (such as specifying the value returned when anout-of-bounds argument is supplied).

Use the same capitalization and punctuation as you used in @param.

@deprecated    (reference page)

The @deprecated description in the first sentence should at least tell theuser 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, the Javadoc tool moves the@deprecated text ahead of the description, placing it in italics and preceding itwith a bold warning: "Deprecated".An @see tag (for Javadoc 1.1) or {@link} tag (for Javadoc1.2 or later) should be included that points to the replacement method:

• For Javadoc 1.2 and later, the standard format is to use @deprecated tag and the in-line {@link} tag. This creates the link in-line, where you want it. For example:

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

• For Javadoc 1.1, the standard format is to create a pair of @deprecated and @see tags. For example:

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

If the member has no replacement, the argument to @deprecated should be"No replacement".

Do not add @deprecated tags without first checking with the appropriateengineer. Substantive modifications should likewise be checked first.

@since    (reference page)

Specify the product version when the Java name was added to the APIspecification (if different from the implementation). For example,if a package, class, interface or member was added to the Java 2 Platform,Standard Edition, API Specification at version 1.2, use:

/**
 * @since 1.2
 */

The Javadoc standard doclet displays a "Since" subheading with thestring argument as its text. This subheading appears in thegenerated text only in the place corresponding to where the@since tag appears in the source doc comments(The Javadoc tool does not proliferate it down the hierarchy).

(The convention once was "@since JDK1.2" butbecause this is a specification of the Java Platform,not particular to the Sun JDK or SDK, we have dropped "JDK".)

When a package is introduced, specify an @since tag in itspackage description and each of its classes. (Adding @sincetags to each class is technically not needed, but is our convention,as enables greater visibility in the source code.) In the absenceof overriding tags, the value of the @since tagapplies to each of the package's classes and members.

When a class (or interface) is introduced, specify one@since tag in its class description and no@since tags in the members. Add an@since tag only to members added in a later versionthan the class. This minimizes the number of@since tags.

If a member changes from protected to public in a later release, the@since tag would not change, even though it is now usable byany caller, not just subclassers.

@throws (@exception was the original tag)    (reference page)

A @throws tag should be included for any checkedexceptions (declared in the throws clause), as illustrated below,and also for any unchecked exceptions that the caller mightreasonably want to catch, with the exception ofNullPointerException. Errors should not be documentedas they are unpredictable. For more details,please seeDocumenting Exceptions with the @throws Tag.

/**
 * @throws IOException  If an input or output 
 *                      exception occurred
 */
public void f() throws IOException {
    // body
}

See theExceptionschapterof the Java Language Specification, Second Edition for more on exceptions.Also see order of multiple @throws tags.

@see     (reference page)

Also see order of multiple @see tags.

@serial

@serialField

@serialData  

(All added in Javadoc 1.2)    (reference page)

For information about how to use these tags, along with an example,see "Documenting Serializable Fields and Data for a Class,"Section1.6 of the Java Object Serialization Specification. Also see Sun'scriteria forincluding classes in the serialized form specification.

{@link}   (Added in Javadoc 1.2)    (reference page)

For conventions, see Use In-Line Links Economically.