Laboratory: Javadoc

Summary: In this laboratory, you will have the chance to improve your skills regarding code documentation and testing.

Preparation

Open your project from the inheritance lab in Eclipse.

You need not add comments to those classes. (At least not yet.)

Exercises

Exercise 1: Generate Documentation

a. Use Eclipse's Javadoc tool to generate Javadoc for these classes.

You can generate Javadoc by selecting Generate Javadoc from the Project menu.

That tool will ask you where to put the documentation. You can put it within your project, but you may find it useful to put it elsewhere, such as in your public_html directory (presuming you have such a directory).

b. Preview the Javadoc documentation in Eclipse.

c. Preview the Javadoc documentation in your Web browser. You will use a URL like file:///home/username/path/to/project/doc/index.html.

Exercise 2: Adding Real Comments

As you may recall, a Javadoc-style comment begins with a slash and two stars and ends with a star and a slash. Add some Javadoc-style comments to various portions of your classes, rebuild the documentation, and determine the effects.

Exercise 3: Protection Levels

You may have noted that the Javadoc documentation does not list package methods and fields. Figure out how to get the Javadoc documentation to reveal more or fewer components.

Exercise 4: Preconditions and Postconditions

Although the Javadoc designers did not acknowledge the need for preconditions and postconditions, we know that they are quite useful.

a. Add a precondition to the Javadoc documentation for a method using the @pre tag.

b. Add a postcondition to the Javadoc documentation for a method using the @post tag.

c. What do you expect to happen when you generate the documentation?

d. Check your answer experimentally.

e. As you probably discovered, Eclipse doesn't yet know about these tags. Configure the Javadoc tool to add the following flags.

-tag pre:cm:"Preconditions:"
-tag post:cm:"Postconditions:"