Download TechRepublic`s Java Anthology Painless documentation using

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