Using JavaDoc

Introduction

If you have a system of classes which are designed to interact (like the canvas), it is useful to have good documentation describing in detail the various methods and classes of that system. The javadoc tool creates such documentation from .java files. The tool scans each .java file for class names, method names, arguments, and properly formatted comments to generate a very navigable web page. For example, the JDK 1.3 API is documented with this tool. The JDE used in CS101 has convenient options for the creation of javadoc documentation.

Usage

To demonstrate the features of javadoc, we will create and document a simple class called (you guessed it) SimpleClass.

Before you run javadoc on this class, you must specify which java file you want to run it on. To do so, select JDE->Project->Options->Javadoc from the menu bar. Once you are there, scroll all the way to the bottom to the Jde_Javadoc_Gen_Other field, and enter SimpleClass.java in the field next to it:

If you wanted to run javadoc on more than one class, you could put either several filenames separated by a space or just *.java to catch every .java file in the current directory. Now scroll about halfway up and search for the Jde_Javadoc_Gen_Window_Title option. Fill that field with a descriptive name, for example A Simple Class. The text you enter here will show up in the Title of the generated web page. To lock in your changes, scroll all the way to the top, and click on the [Set for Current Session] button to lock in the changes. If you wanted to save the changes for the next time you run Emacs, you coud click the [Save for Future Ses sions] button. To close this buffer and go back to your code, select the [Bury Buffer] option.

Now we are ready to actually generate the html files from our code. To do this, select JDE->Make doc. A compiler buffer will show up in your window, and after churning a little bit, the process will be finished. Make sure you are connected to the internet while doing this step -- javadoc relies on web pages at java.sun.com and www.cs.wustl.edu to generate its information. A new directory has been created called JavaDoc, and it contains several html files. Open index.html in that directory with a web browser, and you will see something similar to this.

Now we are ready to add some useful comments for the javadoc tool to interpret and insert into the generated web pages. You are already aware that in java, comments can start with a /* and be terminated by a */. To specify that a comment is to be read by javadoc, it should start with /** instead of /*. Whatever item (whether it be a class, a variable, or a method) directly follows the comment will inherit the comment's text. You can end your comment however you please, as long as Java accepts it. For example, if a simple description is prepended to the file, the text "A Simple Class of our own design" will appear in the section describing our SimpleClass. Note the formatting of the comment -- it starts with a /**. When you are describing a method or a field, only the first line of the comment goes into the Summary section. The whole comment goes into the Detail section.
Also, you can insert @param and @return tags into your comment to specify the properties of a parameter of a method, or the meaning of its return value. Fill in the comments as presented in the screen-shot:

Keep in mind that all tags are optional with javadoc. Now re-generate the javadoc. The pages should look something like this. But wait! There is supposed to be a local variable called localvar that hasn't showed up! This is because by default, javadoc only documents public and protected fields and methods. To include the private components of a class, edit the javadoc options (JDE->Project->Options->Javadoc). Find Jde_Javadoc_Gen_Detail_Switch and select -private. Don't forget to Set for Current Session (or for Future Sessions), and re-generate the javadoc. The newly generated page should look something like this.

By using a lot of generously informative comments, an API can become very easy to navigate, and using the API becomes a breeze. Look at the JDK 1.3 API to see what kind of information to include in your comments.

For more information about using the javadoc tool, go to the javadoc tool page. The options in the Jde_Javadoc_Gen group are similar in name to tags that may be used with javadoc. Using the customization buffer, you are able to specify whether or not to include certain tags, and what arguments some tags should have.