Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
TechRepublic's Java Anthology www.techrepublic.com Painless documentation using Javadoc April 19, 2001 Lamont Adams The problem with writing documentation is that it usually has to be done in a separate application from your source editor, and it's usually just a duplication of many of your source comments. Java developers have a great alternative to this drudgery in Javadoc, a utility distributed as part of Sun's JDK. Javadoc is a command-line utility that generates surprisingly nice HTML documentation from specially marked comments in your source code. This means that you can maintain your documentation while you maintain your source code and comments. In this article, I'll get you started using Javadoc and show you an example source file and the documentation Javadoc created from it. Special tags Javadoc recognizes a variety of special tags that can be inserted into your comment blocks. Each tag begins with an at (@) symbol and produces a different effect in the generated documentation. Table A lists some of these tags and their effects. Table A @author @author authorname—Indicates the author of the class or interface (There can be multiple authors per tag or multiple tags per class, in which case all authornames wind up on the same line in the documentation.) @version @version version—Inserts a version line with the version number indicated by version @param @param parametername parameterdescription—Documents parameters passed to methods and constructors (Parametername is the name of the parameter, while parameterdescription is the description of that parameter and can span multiple lines.) @return @return returntext—Documents the return value of a method with returntext @exception,@throws @exception exceptionname exceptiondescription—Synonymous with @throws, @exception indicates which exceptions a method or constructor can throw, one per tag. Exceptionname should be the class name of the exception. @see @see creates "See Also": links in the resulting documentation and has multiple syntaxes: 1. @see packagename.classname#membername textlabel—Refers the reader to see the membername member of class classname in package packagename for more information (Membername is optional.) 2. @see "Some Text"—Creates a "See Also" link referring the reader to "Some Text" 3. @see <a href=http://SomeUrl.com /a>—Creates a link referring the reader to the URL specified in the HTML href tag @deprecated @deprecated explanation—Marks a method as deprecated, meaning obsolete or not to be used anymore (The explanation is displayed at the top of the class' documentation file.) @link {@link packagename.classname#membername textlabel}—Similar to syntax 1 of @see; provides an inline hyperlink to the member of the class specified Javadoc tags ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 1 TechRepublic's Java Anthology www.techrepublic.com To use a tag, just embed it in a comment block beginning with a /** comment marker, and you're in business. Javadoc ascribes a comment to the code item it directly precedes. Here's an example of code containing some Javadoc comments and special tags: package DocExample; /** This is a class comment * @author Lamont Adams * @version 1.1 * @see java.io.BufferedInputStream#ReadLine ReadLine() * @see "A good book on beginning Java is Thinking in Java, by Bruce Eckel" * @see <a href="http://www.techrepublic.com/republic.jhtml?id=r008">Developer Republic rocks! </a> */ public class DocExample { /** This is a field variable comment. * i gets initialized to zero. * Javadoc comments can span multiple lines */ protected int i=0; /**Here's the constructor comment */ public DocExample() { /* this comment won't be included in the documentation*/ i=1; } /** finally we have a method comment * @since Version 1.0 * @param WhatToDo what the programmer wants DoSomething to do * @return How many times WhatToDo was performed */ public int DoSomething(String WhatToDo) { return 1; } } Tricky packages Building package-level documentation is not quite as simple. You might think putting comments above the package statement in a source file would do the trick, but Javadoc will ignore these, leaving you scratching your head. Upon reflection, this limitation seems obvious. There is no single source file to represent a package, so there is no way to associate a Javadoc source comment with a package. Instead, you should use a template provided by Sun, which JavaDoc will happily use to create your package-level documentation. Generating your documentation As I mentioned, Javadoc is a command-line utility, which unfortunately makes it a little difficult to use. If you find yourself using it regularly, I'd recommend creating a script or BAT file that launches it with your preferred set of options. The syntax for invoking Javadoc on Windows is: Javadoc –options Packagename [Packagename1 ... PackagenameN] where –options can be one or more of a long list of command-line switches that alter Javadoc's behavior by limiting the tags Javadoc processes, restricting Javadoc to certain pieces of code, or even grouping multiple packages in the documentation. (For a complete list of Javadoc command-line options, see Sun's Javadoc documentation.) Packagename is the name of the package for which Javadoc is to generate documentation. You can specify multiple packages on the command line by separating them with spaces. Alternatively, you can list the packages you want Javadoc to document in a text file and specify the filename on the command line preceded by an at character: ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 2 TechRepublic's Java Anthology www.techrepublic.com Javadoc –options @PackageFileName This is probably the best approach if you have quite a few packages to document and you generate your docs for them regularly. Javadoc looks for packages in your Classpath and creates the documentation in the same directory or directories as your package source code unless you specify a destination folder with the option switch d: Javadoc –d "C:\MyDocuments\JavaDocuments\" @PackageFile Check Figure A at the end of this article for a sample of the class-level documentation Javadoc produced from the sample code introduced above. In addition to the class documentation, Javadoc by default also produces at least the following documents: Class hierarchy page Alphabetical index page Deprecated page, listing all deprecated items Summary page, listing all classes in the package There would normally be links to these documents in the class documentation page, but we removed them from our example document for logistical reasons. Custom documentation What if you want to include your own custom tag or want your documentation in another file format, such as PDF? No sweat. You just need a custom doclet. A doclet is a Java class that implements Javadoc's API in order to produce custom documentation. All the tags we described in Table A are provided by the "standard" doclet, which Javadoc uses by default. To make Javadoc use a custom doclet, include the – doclet option, along with the classname of the custom doclet, on the command line. For more information on developing your own doclets, see this doclet overview on Sun's Web site. Javadoc is an excellent tool that takes a lot of the drudgery out of building code documentation, but it's screaming to have a GUI front end built for it. Then, maybe developers would have to find some other excuse for not writing their documentation. ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 3 TechRepublic's Java Anthology www.techrepublic.com Figure A: Sample JavaDoc Page ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 4 TechRepublic's Java Anthology www.techrepublic.com Ten tips for creating killer Java docs July 13, 2001 Kathrine Wright Software maintenance is a significant part of the effort and cost put into an application over its lifetime, so writing code documentation for an application is essential. Unfortunately, code documentation often ends up on the "do later" list, and your amazing code later becomes a problem child to maintain. Luckily, Java programmers have at their disposal a tool to make documenting code easier. Javadoc The previous article provides an overview of Javadoc, a tool that ships with Sun's JDK toolkit. With a few simple guidelines, you can create killer code documentation using this tool. You can then ensure that you leave smiles on the mugs of the programmers left to follow your code after you move on to a bigger and better project or company. The Javadoc utility works by creating a set of HTML files out of the Java source files that end in a .java extension. Within your comments, you can add HTML tags to control the format. Comments included in the HTML files are those that start with a double asterisk. With a bit of planning, you can become the programming guru who is also known for amazing documentation skills, because Javadoc renders specially marked comments into lovely HTML code. In fact, even if you never enter a single code comment, Javadoc produces a fine set of HTML pages that make the code easier to decipher. You already build strong comments as part of your routine? Then you know that consistency and simplicity are critical in any good standard. For Sun’s recommendations on developing and documenting your source code, see "How to Write Doc Comments for the Javadoc Tool.” Make your docs even better with these tips Even though Javadoc does a lot of the work, you can greatly improve the quality of your documentation by applying some standards and consistency to your comments. Here are 10 tips to get you started: 1. Save time. For package documentation, start with the template, and comment as you go. 2. Work with your writing staff to adopt an official set of standards for your code documentation. You may want to adopt an already published style guide and make minor customizations. (Why not take advantage of the knowledge someone else paid to obtain?) Distribute the guide among the project team members and check periodically for compliance. Style resource The Elements of Java Style, also known as the RogueWave Java Style Guide, provides a straightforward presentation of techniques for producing good documents and makes recommendations for building good code too. This set of standards was created by a development shop specializing in Java and C++ development for “programmers who are writing Java as part of a team.” 3. Create a comment for each protected or public member variable, method, and class. It’s important to note that creating names for variables, methods, and classes is the first opportunity to convey how the code works. If you create meaningful names in the first place, you eliminate the need for lengthy comment. A good question to ask is, “Can the next programmer who looks at this code understand how it works by reading the name?” When the name doesn’t fully convey how the code works, use comments to explain their purpose, any variables, etc. 4. Because member variables, methods, and classes usually describe things rather than actions, you can write a succinct phrase such as "A text box" instead of "This field is a text box." 5. Follow Sun’s guidelines for using and ordering tags. For ordering multiple tags, list them in the following order: ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 5 TechRepublic's Java Anthology www.techrepublic.com @author: List chronologically @param: List in argument-declaration order @exception: List alphabetically @see: List from “nearest to farthest access, from least-qualified to fully qualified” 6. For the tag @param, indicate whether a parameter can be null or is required. 7. Keep the writing style active and simple. Sun recommends that the first sentence of each doc comment should summarize the member, class, interface, or package and that you use phrases rather than complete sentences. (Note that if you use any abbreviation ending with a period and then a blank, tab, or line terminator, you should type an HTML metacharacter such as   immediately after the period if you want your full sentence included in the summary created by Javadoc.) 8. Code comments should be used to help programmers understand what code does. Use comments to explain code and use a source code control tool to audit code changes and track defects. If you choose to document bugs in the comments anyway, provide a consistent, easily recognizable format to minimize clutter. 9. Create a procedure in the top of class documentation if a class will be reused (extended) into many subclasses and there is a specific set of steps to implement them. List each step in the process and use HTML list tags (<ol> or <ul> and <li>) to format the comments. 10. Generate a new set of HTML files at regular intervals, such as once a week, to make sure necessary information has been captured and to edit information while it's still fresh in your mind or the minds of team members. Conclusion Writing program documentation may never be fun, but it is necessary. With Javadoc, the task of documenting your Java programs has just gotten easier. And if you follow some simple standards as you write your programs, there is no reason why you can’t be known for world-class documentation, as well as world-class code. ©2002 TechRepublic, Inc. www.techrepublic.com. All rights reserved. Page 6