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