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.  */ 



Java Garage
Java Garage
ISBN: 0321246233
EAN: 2147483647
Year: 2006
Pages: 228
Authors: Eben Hewitt

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net