[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
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
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.