Introduction to JavaDoc

   

Java™ 2 Primer Plus
By Steven Haines, Steve Potts

Table of Contents
Chapter 10.  Java Classes


To effectively use Java's prebuilt classes you need to know what they can do and how to find the ones you want. Therefore there has to be a mechanism you can use to learn each class's methods, the parameters that they accept, the values that they return, and, most importantly, what the method does. Some classes are documented using the tool called JavaDoc, which parses Java source files looking for comments preceding methods that have a very special format and core tags.

Sun's methods are all documented using JavaDoc, and you'll find that your users will be able to effectively use your classes if you comment your methods using this standard instead of generating your own JavaDoc documentation. Before I show you all the intricate details of commenting your code for use with JavaDoc, take a look at Figure 10.1 to see the results. At the time of this writing you can access the following JavaDocs at http://java.sun.com/apis.html.

Figure 10.1. Sun's JavaDoc classes

graphics/10fig01.gif

Looking at Figure 10.1, the upper-left corner shows all the available packages from which you can explore their classes. Java allows you to group similar classes into packages for both organizational purposes as well as some special security settings. The lower-left corner shows all the classes available to you. If you select a package from the upper-left corner, only its classes will appear in the lower-left corner. The right side of Figure 10.1 shows the details of all the packages shipped with the Sun SDK. When you click a package you'll see a description of the classes contained within the package. When you click an individual class you'll see a description of the class, a list of all its attributes, a summary of all its methods, and a detailed list of its methods, including usage.

To add JavaDoc comments to your classes, the general form of a comment is as follows:

 /**   * This is the description part of a doc comment   *   * @tag    Comment for the tag   */ 

The comment starts with a forward slash followed by two asterisks, and ends with a single asterisk followed by a forward slash. You can place JavaDoc comments at the beginning of a class (preceding the class declaration) to provide a description of the class's functionality, or at the beginning of the method (preceding the method declaration) to provide a description of the method's functionality. Furthermore you can place comments before public constants and variable declarations.

JavaDoc defines a specific set of tags that have meaning dependent on their context (see Table 10.1).

Table 10.1. JavaDoc Tag Definitions

Tag

Description

@author

Denotes the author of the class (classes and interfaces only, required)

@version

Denotes the version of the class (classes and interfaces only, required)

@param

One parameter tag is specified for each parameter that is passed to the method (methods and constructors only)

@return

Describes the return value of the method (methods only)

@exception

One throws/exception tag is listed for each exception that the method can throw (@throws is a synonym added in JavaDoc 1.2)

@see

References another class or method

@since

Defines the version of the API that this method/class has been defined since

@serial

Documents serializable fields in this method (or @serialField or @serialData)

@deprecated

Notes that this method has been deprecated, which means that it can possibly be removed at some future time and users of your class should make notes and stop using this method

For example:

 /**   * Doubles an integer   *   * @param i     The integer to double   * @return    An integer containing the doubled value   */  public int double( int i ) {    return 2*i;  } 

refers to the following URL for complete documentation on using JavaDoc:

http://java.sun.com/javadoc


       
    Top
     



    Java 2 Primer Plus
    Java 2 Primer Plus
    ISBN: 0672324156
    EAN: 2147483647
    Year: 2001
    Pages: 332

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