This chapter is from the book
This chapter is from the book
This chapter is from the book
7.2 Documentation with JavaDoc
You can automatically create documentation for your applications using special Java comments in your source files, and you can then extract them with the javadoc tool. This has many advantages: Instead of having to go through a separate process of documentation (which people are less likely to do anyway), allowing the documentation to emerge directly from comments in the program itself means the docs are more likely to be up to date, complete, and standardized. Because the pages generated are HTML pages, they are immediately available for distribution in a common format. All of the HTML documentation for the Java API was generated using JavaDoc.
The javadoc tool comes with the standard JDK, and it is easy to use.
NOTE
This is the third tool we have looked at so far, javac for compilation and java for program execution being the others. You can view other tools available in the standard JDK by peeking into the <JAVA_HOME>/bin directory.
There are two requirements for creating this documentation: You must add the comments to your file, and then you must run the javadoc tool to extract the comments and create the HTML files from them.
The javadoc tool extracts comments for the following:
Packages
Public classes and interfaces
Public and protected methods
Public and protected fields
Private items are not included. It is a good idea to comment all of these items in your code. Write your comments immediately above the items in the code.
7.2.1 Creating JavaDoc Comments
You notate comments that you want to be picked up by javadoc like this:
/** some comments */
Putting the extra * after the first comment line means that the compiler will rightly ignore your comment as a regular comment, but javadoc will know to pick it up. Note that any JavaDoc comments must be outside a method.
Generally, it is a good idea to include information about the creator, creation date of the file, and other information just as you would comment a ColdFusion custom tag:
/** * <p>Title: SomeClassFile</p> * <p>Description: This file prints <b>'Hello!'</b> to the command line</p> * <p>Copyright: Copyright (c) 2003</p> * <p>Company: WWWBooks</p> * @author E Hewitt * @version 1.0 */ ...class definition here...
Notice that in the comments there are two kinds of symbols used: HTML paragraph tags and the @ symbol. You can write any HTML in here, though the use of heading tags is generally discouraged because it can conflict with the JavaDoc formatting and distort the layout.
7.2.2 JavaDoc Tags
The @ symbol inside a JavaDoc comment denotes a tag. There are several tags you can use, and they display different kinds of information in the generated document. A description of each follows:
7.2.2.1 @author author
Documents the author of the class. Use one @author tag for each author. You might need to use the -author option during the javadoc execution for the @author field to be included.
7.2.2.2 @deprecated description
Indicates that the class, method, or variable is deprecated and should not be referenced in the future. The description text should indicate what to use instead of the deprecated item, for example:
@deprecated Use <code>anotherMethod(String s)</code>
The description message may indicate other information about the nature of the deprecation; it can be used for classes, variables, and methods.
7.2.2.3 @docRoot path
Specifies the path to the root directory of this documentation.
7.2.2.4 @exception exceptionName and explanation
Identifies an exception that a method throws and describes in what circumstances the exception might occur. Can only be used for methods.
7.2.2.5 {@link name text}
Inserts a link inline to another item with related information. name indicates the name of a class or method to which the link will be added. The text is displayed.
7.2.2.6 @param name
Identifies a parameter for a method. Can only be used in documenting a method.
7.2.2.7 @return value
Identifies a method's return value. Can only be used in documenting a method.
7.2.2.8 @see link
Adds a hyperlink to more information, for example:
@see href @see packageName.className#member text
The first way of writing this is to specify as href an absolute or relative URL. The second form specifies the name of a class in a package and, optionally, the name of a member. The text parameter is also optional.
7.2.2.9 @serial link
Adds a hyperlink in the "see also" section. More information on this tag appears below.
7.2.2.10 @serialData description
Comments the data written by the writeObject() and writeExternal() methods.
7.2.2.11 @serialField name type description
Comments an ObjectStreamField component.
7.2.2.12 @since versionNumber
Adds a since element. Its value should be a description of the release that first introduced this feature. For example, @since version 1.3.1. Can be used for documenting classes, variables, and methods.
7.2.2.13 @throws exceptionName and explanation
Has the same usage and meaning as the @exception tag.
7.2.2.14 @version description
Identifies the version of a class. Example:
@version version 1.0
You may need to explicitly specify the -version argument when using the javadoc utility.
7.2.3 Package Comments
You can create comments regarding your packages by adding a file named package.html to each package directory. All of the text you write between the <body> tags will be extracted when you run the javadoc command (we'll see how to do this in a moment).
7.2.4 Overview Comments
It is often useful to supply a general comment on all source files. To do this, create a file called overview.html in the parent directory for all application source files. As with the package.html file, anything between the <body> tags will be extracted. The comments are shown to the user when Overview is selected from the nav bar.
7.2.5 Doclets
Documentation using javadoc is a wonderful feature of the JDK. But all of the documentation conforms to the same look and feel as the docs that come with the JDK itself for describing classes in the Sun packages.
While you can specify your own stylesheet for use with javadoc, you may wish to include a more customized interface for your comments. If you have this kind of specialized requirement, doclets provide a way for you to create very customized documentation. See the online documentation on doclets at http://www.sun.com for more information.
7.2.6 Extracting Comments
In order to extract the JavaDoc comments you've written into your files, you use the javadoc command. Using the javadoc tool for extraction creates new HTML files in appropriate folders based on your comments. To do this, follow these steps:
Navigate to the directory that contains the source files you wish to create documentation for. You must be in the parent directory for all of the application's source files (usually com). This directory also contains the overview.html file if you wrote one.
If this is a single package, run the javadoc tool by issuing the command javadoc -d docsDirectory packageName. The docsDirectory here is the name of the directory you want to create the HTML files in.
If you have multiple packages, run this command: javadoc -d docsDirectory packageName1 packageName2....
If all of your files are in the default package, you can issue this command: javadoc -d docsDirectory *.java.
Note that you can use many different options when running the javadoc tool. To see what the options for this tool are, you can simply run javadoc. This will give you an error message that says you've not supplied the correct parameters, and it will therefore also show you all of the correct parameters, as shown in the next section.
7.2.7 JavaDoc Usage
Usage for the javadoc tool is shown below:
usage: javadoc [options] [packagenames] [sourcefiles] [classnames] [@files]
Some of the notable arguments available are shown below:
-overview <file> Read overview documentation from HTML file
-public Show only public classes and members
-protected Show protected/public classes and members (default)
-package Show package/protected/public classes and members
-private Show all classes and members
-help Display command line options
-doclet <class> Generate output via alternate doclet
-docletpath <path> Specify where to find doclet class files
-sourcepath <pathlist> Specify where to find source files
-classpath <pathlist> Specify where to find user class files
-exclude <pkglist> Specify a list of packages to exclude
-subpackages <subpkglist> Specify subpackages to recursively load
-source <release> Provide source compatibility with specified release
-extdirs <dirlist> Override location of installed extensions
-verbose Output messages about what javadoc is doing
-locale <name> Locale to be used, e.g., en_US or en_US_WIN
-encoding <name> Source file encoding name
Some notable arguments include the ability to specify your own stylesheet for the documentation. If you don't specify one, your JavaDocs will look like the Sun JDK docs.
Let's write a simple class just to make some comments and see how they are generated into HTML documentation by JavaDoc.
7.2.8 Comments.java
/*
* Comments.java
*
* Created on June 6, 2002, 9:09 AM
*/
package chp7;
/**
* The <code>Comments</code> class is <i>very</i>
* sophisticated. It's like a TS Eliot poem:
* there are more comments than code!
* @author eben hewitt
* @version 1.0
*/
public class Comments {
private String msg = "This is the Comments class.";
/**
* Public default constructor.
* Creates a new Comments object.
*/
public Comments() {
}
/**
* @param args the command line arguments
*/
public static void main (String args[]) {
Comments myComments = new Comments();
System.out.println(myComments.showMsg());
}
/**
* This method gets the msg String and returns it.
* @return The value of <code>msg</code>, which is a
* String message to the user
*/
public String showMsg() {
return msg;
}
/**
* @deprecated This method is deprecated because it
* breaks encapsulation.<br>
* It has been replaced by showMsg().
* @see Comments#showMsg() showMsg().
*
*/
public void printMsg() {
System.out.println(msg);
}
}
7.2.9 Generating the Comments.java JavaDoc
There are generally two ways to create the JavaDoc. You can do so at the command line, or you can use your IDE of choice. Here's how you would do it for Comments.java in Forte (Sun ONE Studio):
Once you've written the comments and you're ready to create the JavaDoc, right click anywhere in your source code file. A context menu appears. Choose Tools > Generate JavaDoc.
Forte generates the comments and asks if you would like to view them in a browser. If you have not specified a directory, Forte will automatically create the folders and files under a subdirectory of Forte, like this:
C:\forte4j\bin\projects\javadoc\index.html.
Since this obviously isn't very workable, remember to use the @docRoot tag to specify a directory.
Here's what we type at the command line if you prefer this method:
At the command prompt, navigate to the directory that contains the package you want to document.
Type javadoc -d docsOutputDirectory nameOfPackage. To generate the docs for the Comments file in the chp7 package that we just wrote, I type this:
C:\jdk1.4\JavaForCF>javadoc -d C:\MyJavaDocs chp7
The utility lets you know what it's doing, and after a moment, your directory will be created and you can view your documentation. Open the index.html page, and a link to the Comments class documentation will be presented. See Figure 7.1.
)
Figure
7.1 Generated JavaDoc comments.
In ColdFusion it is very important to comment your work. While the javadoc utility makes it very easy to generate sophisticated and usable documentation, it also requires more effort: It forces you to comment everything that's public. It's a good practice to get into. We can't do it in the code examples in this book because of space considerations, but do comment your work.