Using Javadoc Tags

You can use the following tags in your Javadoc comments. These get picked up by the tool to serve as the text for your documentation.

• @author Who wrote this class. Use this only with classes and interfaces, not methods. Use separate @author tags for each author if there's more than one.

• @version Identifies the version of the class. Use only with classes and interfaces. Use the following values:

  /**
   * @author eben.hewitt
   * @version 1.0
   */
   

• @param Indicates a parameter to a method or a type parameter to a class. Use a separate @param tag for each parameter. For use in methods and constructors only. Don't include the param's type, just its name and description, as in the following:

  /** for method:
   * @param salary The boss's current salary.
   * @param schmoozability How much this boss can
   * schmooze, represented on a scale of 900-1000
   */
  
  /** for class type parameter:
   * @param <T> Some class parameter.
   */
  

• @docRoot Path to the root directory of the documentation, as in the following:

  * This class is a member of the
  * <a href="{@docRoot}/../guide/collections/index.html">
  * Java Collections Framework</a>.
  

• @return Identifies a method's return value. Obviously, this is for use only with methods.

  /**
   *@ return The boss's bonus
   */
  

• @throws Indicates exceptions thrown by this method. Should be used to describe under what circumstances this exception might be thrown. @exception is also acceptable in place of this, but I prefer the active verb.

• @see Points to other relevant classes with a hyperlink, as in the following example:

  /**
   * @see packageName.ClassName#member text
   */
  

• @since Indicates the release of your software that first introduced this feature. Can be used with classes, methods, and fields.

  /**
   * @since 1.2
   */
  

• @deprecated Indicates that a method or class is deprecated and shouldn't be used. Write it like this:

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

• {@value arg } Accepts the name of a program element and label. This way, it can be used in any doc comment, not just constant fields.

  /**
   * @value package.class#member label
   */
  

• {@literal tag } Denotes literal text so that the Javadoc tool does not attempt to interpret enclosed text as containing HTML or Javadoc tag.

• {@link link} You use the @link tag inline in paragraph text to have the Javadoc tool automatically generate a hyperlink to the Java class or method you specify, as in the following example:

  import ...
  /**
   * Uses NIO to read in the datafile initially using a
   * @link java.nio.ByteBuffer} and a {@link
   * java.nio.CharBuffer}, and then stores the
   * complete file in a synchronized list.
  **/
  public class SomeClass { ... }
  

The above will generate a hyperlink to the Javadoc for the class indicated. Notice that you can add a # following a class name to indicate a method you want to link to directly. Doing so means that you have to supply the types of each parameter to the method, but not the parameter names, as in the following example of Javadoc for a public method:

/**
 * This client-facing method should be
 * preferred for clients over the {@link
 * mypackage.db.DataClass#updateRecord(long,
 * java.lang.String[], long)} method.
 */