Lab 5: Javadoc

Purpose: In this lab, you will practice using Java's javadoc documentation generator.

Preliminaries

In Java's object-oriented model, programs are collections of communicating objects. One advantage of this model is that it is possible to reuse an object in multiple programs. However, if we are to reuse objects, it is important that the behavior of the objects be clearly and uniformly documented.

Java provides a standard comment syntax for describing such behavior. We call the comments designed for general use descriptions javadoc comments. The standard Java development kit also provides a program for converting those comments into useful web pages.

Javadoc-ing your programs

Javadoc, Sun's Java documentation generator, creates HTML files which are accessible on the World-Wide Web. The tradition on our Unix machines is that all your web files should be in the directory /home/user/public_html, which must be world-readable and world-executable. If you don't already have such a directory, create one. You may want to make a subdirectory for your Java docs (so that when you build other HTML pages they can be separated from your Java docs).

Step 0. In order for the Java documentation to be readable, you'll need to copy a set of images to whichever directory you'll be using for your documentation. Make a soft link to the images directory with

% ln -s home/rebelsky/public_html/jdk1.1.3/docs/api/images .

You are now ready to build your Java docs.

Step 1.

Change to whichever directory you're using for your documentation and type

% /home/rebelsky/bin/jdoc -author -version Circle.java

This will create the HTML file File.html (as well as index.html and packages.html). Move that file to your public_html directory (or appropriate subdirectory).

If you don't have a copy of Circle.java or didn't use Javadoc-style comments, consider using my Circle.java.

Step 2. See what your HTML looks like. In Netscape, you can then view the HTML by using the URL "http://www.math.grin.edu/~user/File.html".

Step 3. Try rebuilding the documentation using the -public flag. What difference does this flag make.

Step 4. Learn about the options to Javadoc with

% javadoc -help

Step 5. Some people find the images in Javadoc documentation cumbersome. I've created a small program that strips out the images. Try runing that program, called fixdoc, as in

% fixdoc Circle.html

What happens? Which version of the documentation do you prefer?

Step 6. If you still have time, you may want to add appropriate comments to your Java source code and re-javadoc the file. You can gain some control over the appearance of the documentation by appropriate use of HTML codes.

• <strong>stuff</strong> strongly emphasizes stuff (most typically, making it bold).
• <em>stuff</em> emphasizes stuff (most typically, making it italic).
• <p> separates paragraphs.
• <br> insets a break (a carriage return).

References

You can find more information on javadoc at

• http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
• http://www.math.grin.edu/~rebelsky/jdk1.1.3/docs/tooldocs/solaris/javadoc.html
• http://java.sun.com/docs/books/jls/html/18.doc.html

History

• Created early February, 1998, for CSC151 98S.
• Updated February 15, 1999, for CSC151 99S.