Section 5.5. Complete, Up-to-Date Program Documentation Made Easy
|
5.5. Complete, Up-to-Date Program Documentation Made EasyOne of Java's most useful features is javadoc, a command that (by default) produces comprehensive HTML program documentation directly from the program source. Since it works from the source, it can be automated, and you may be certain that the documentation is up-to-date. It takes much of the documentation burden off of programmers and permits new programmers to join a project and rapidly come up to speed because there is comprehensive documentation in a standard format. The javadoc tool produces HTML documentation by default, but this is because it uses a doclet that produces HTML documentation. You can write your own doclet that produces whatever format you wish. Most find the HTML documentation so satisfactory that custom doclets are rare. Javadoc can be a large topic, because it not only documents all classes, methods, and class variables, but can also use detailed text from specially formatted comments in the source code. We will cover Javadoc comments only briefly here, but you will see examples in our project code throughout this book. 5.5.1. Running javadocThe javadoc command has the following general form: javadoc [options...] [package names...] [source filenames...] [@optfile...] Options are covered in the next section. You can specify the classes to document in two ways. First, you can list one or more Java packages on the command line. Source code for the named packages is searched for on the source classpath (see Section 5.5.2). Wildcards are not permitted in package names. Second, you may list as many Java source files as you like, and you may use wildcards in the names. As with the javac compiler above, the @optfile allows you to name a text file whose lines are treated as arguments as if they had been typed on the command line. Example 5.5 shows how to run javadoc on our small multiclass sample. In this case, we were in the "base directory" of the package when we ran the command. In other words, net was a subdirectory of the current working directory when we ran Javadoc. Javadoc uses the same default classpaths and environment variables as javac does, so by default "." is on the path. Generally, specifying packages is the most convenient way to document a number of classes, since packages are how collections of classes are generally managed in Java development. Figure 5.1 shows the main screen of the documentation thus produced. Figure 5.1. Javadoc documentation viewed in Konqueror Web browser Example 5.5. Running javadoc with defaults against a package$ javadoc net.multitool.Payback Loading source files for package net.multitool.Payback... Constructing Javadoc information... Standard Doclet version 1.4.1 Generating constant-values.html... Building tree for all the packages and classes... Building index for all the packages and classes... Generating overview-tree.html... Generating index-all.html... Generating deprecated-list.html... Building index for all classes... Generating allclasses-frame.html... Generating allclasses-noframe.html... Generating index.html... Generating packages.html... Generating net/multitool/Payback/package-frame.html... Generating net/multitool/Payback/package-summary.html... Generating net/multitool/Payback/package-tree.html... Generating net/multitool/Payback/Account.html... Generating net/multitool/Payback/Cost.html... Generating net/multitool/Payback/DebtAccount.html... Generating net/multitool/Payback/Payback.html... Generating net/multitool/Payback/Purchase.html... Generating net/multitool/Payback/SavingsAccount.html... Generating package-list... Generating help-doc.html... Generating stylesheet.css... $ 5.5.2. Javadoc Command-Line OptionsAs with other options documentation in this chapter, this is not intended to be a complete reference document. We are documenting only the most important command-line switches. -public Causes only public classes, members, and methods to be documented. You might want this for end-user documentation of a library. -protected Causes public and protected classes, members, and methods to be documented. This is the default documentation level. This is also the most likely level at which you would want to document code meant for distribution. -package We suspect you can see where this is going. This switch causes package, protected, and public classes, members, and methods to be documented. -private This switch causes all classes, members, and methods to be documented. In our experience, this is the setting you will want to use for internal projects. It documents everything. -sourcepath and -classpath These are the paths that will be searched for source classes or referenced classes. These switches work like the corresponding switches for the javac compiler. -verbose and -quiet These switches control how much output is produced as javadoc runs. If you choose -verbose, detailed information is produced (more than the default; in current versions, this option mostly shows time measurements of the parsing of each source file). If you choose the -quiet option, progress messages are suppressed completely. -doclet starting_class We're not going to go into too much detail on this, but this switch allows you to name a doclet (a class that uses the Doclet API) to use in place of the default doclet. See the next paragraph for more information. All of the switches documented so far are provided by the javadoc program itself. Javadoc, like the rest of the Sun Microsystems Java SDK, is written in Java. The authors of javadoc took advantage of this. The default behavior of javadoc is to produce HTML documentation with a standard look and feel. However, there exists an API, called the Doclet API, which allows you to write a Java class of your own to process the information parsed out of the source by javadoc. For details, see the Doclet Overview[3] on Sun's Web site.
Sun provides a default doclet that produces HTML documentation. That doclet takes a number of command-line options as well. We'll cover the most important of those now. Remember, these are provided by the standard doclet. If you use the -doclet switch, then these switches will not be available (unless, of course, the alternate doclet just happens to provide them). -d directory By default, the HTML documentation is saved in the same directory as the source. Use this switch to specify an alternate directory into which documentation is to be placed. -use Causes javadoc to generate a "Use" page for each class and package. Such a page is a cross-reference to all uses of the class or package. -version Causes any @version tag data to be included in the documentation. If you are using CVS for source control (and why wouldn't you?) we recommend adding $Id$ after the version tag, which CVS will automatically replace by its ID string containing the filename, CVS revision number, date/time and the author of last check-in. (For more about CVS, see Chapter 8.) -author Causes any @author tag data to be included in the documentation. -splitindex Causes the alphabetical index to be broken into multiple pages, one per letter. Can be useful when you have a very large number of classes and/or packages documented in a single Javadoc document set. -windowtitle title Sets the title for the document set. The text that follows this switch will go into the HTML <title> element on documentation pages. -nodeprecated This causes all deprecated methods and classes to go undocumented. Normally they are documented, but marked as deprecated. -nodeprecatedlist Drops deprecated classes and methods from indexes, lists, and cross-references, but leaves the actual documentation in place. There are actually many more switches. Some of the most important that we haven't covered are the -link, -linkoffline, and related tags. If you end up producing many API packages and document them separately, you can use these switches to link your separate Javadoc documentation together seamlessly, so that when you use classes from separately documented packages, the references in the documentation for your code will be live links to that separate documentation. For details on these and other switches, see the Sun documentation on javadoc.[4]
5.5.3. Javadoc CommentsThere's more to Javadoc than just documenting the types and names of classes, methods, and arguments. A developer can annotate or supplement the documentation by placing specially formatted comments in his or her code. A Javadoc comment begins with the C-style open comment plus at least one more asterisk. It ends with a C-style close comment. In other words: /* This is a C-style comment, but it is _not_ a Javadoc comment. */ /** This is a C-style comment, but it is also a Javadoc comment. */ This isn't a part of the Java programming language. It is merely a lexical hack to allow the javadoc program to recognize a comment it should pick up and process. Javadoc is fairly intelligent about where to place the text extracted from a Javadoc comment. For example, a Javadoc comment placed just before the start of a class will appear in the class summary on the package page and at the top of the class detail page. A Javadoc comment placed just before a method will appear in the method's box on the class detail page, and so on. We encourage you to discover for yourself the relationship between Javadoc comments and the output of the standard doclet. Use it. Experiment. Or, you can go and read the official Sun Microsystems documentation on Javadoc.[5] That's your choice.
Since comment text is extracted and placed into certain positions in an HTML document, you may use HTML tags in your comments to affect how they are rendered. Be aware that when you do so, you may get unexpected results if you use any custom doclets. There's more to it than that, however. There are a number of macros that you can place in Javadoc comments to mark data of particular significance. For example, @author should appear just before the name of the author of a particular piece of code. These at-tags must appear after all descriptive text in a Javadoc comment.[6] A tag must be at the beginning of a line within the comment (ignoring any preceding whitespace or asterisks). The tag's data is everything from the end of the tag to the end of the line (Example 5.6.)
Example 5.6. Sample Javadoc comment with at-tags /** * addWait - adds in the given wait time to all the counters; * we could say much more about the method here, but let me say * that we sometimes include HTML tags directly in our comments. * Since Javadoc will run all our text together, we may need: <br> * break tags <br> * or paragraph tags <br> * for spacing and separation. * <p>We also add <i>other</i> HTML tags for <b>emphasis</b>. * <p>You should still try to make the comment readable, though, * for the programmer who is editing the source, not * just for those looking at the formatted Javadoc. * @author John Q. Programmer * @version $Id$ * * @param delay - elapsed time, in milliseconds * @throws TakesTooLongException * @returns total time, in milliseconds * * @see net.multitool.util.TakesTooLongException, net.multitool.ctrl.Time#count * */ public long addWait(long delay) { // ... } Here are the standard at-tags: @author Everything from the tag to the end of the line is taken as the name of the code's author. @deprecated Marks the method or class deprecated. This tag may be optionally followed by explanatory text. If present, this text should describe when and why the class or method was deprecated and what programmers should use instead. @exception or @throws Only valid in the comment for a method or constructor. This tag is followed by the name of an exception class (a descendant of java.lang.Exception) and optionally by additional explanatory text. The intent is to list the exceptions that the method throws. @param Only valid in the comment for a method or constructor. This tag should be followed by the name of a parameter to the method followed by descriptive text. This is used to document method and constructor parameters. @return Only valid in the comment for a method.[7] This tag is followed by descriptive text meant to document the return value of the method.
@see Populates a "See Also" section in the documentation that will provide hyperlinks to related content. There is a general format for linking to any URL, but the most common use is to refer to other elements in the same Java program. See below for the general format of such links. In addition to these standard at-tags, there are other at-tags that may be embedded in any comment texteither the comment itself or in text that is an argument to a standard at-tag. Such tags are placed within curly braces, for example {@example}, within a Javadoc comment. The one we use the most is the @link tag, which allows you to make a reference to another package, class, method, or class member. The general format is the same as that for the @see tag: package_name.class_name#member_or_method_name Any of these elements is optional. The embedded at-tags include: @docRoot This tag may be used when embedding HTML anchor or image tags (A or IMG tags) in a Javadoc comment to supply the root part of the documentation path. You should always use this instead of hard-coding the full URL, or a change in directory structure or server configuration might break all of your links. @link Allows you to embed a cross-reference to another section of the program's documentation directly in comment text. The format of a reference is the same as that for the @see tag. This list is not complete. As always, see the official documentation[8] for details.
|
|
EAN: 2147483647
Pages: 292