IC211: Lab 4

Finish Lab 3

You know what to do. Do it. Show your instructor.

Javadoc describing an interface

As we have seen, classes enable us to build barriers around data and algorithms so our untrustworthy users can't mess everything up, and our untrustworthy selves don't mess up the programs of our poor users.

But in order to move information around, we used methods that act as go-betweens, mediating between our code and that of our users. But how will our users know how to use our code, especially if we go to all this trouble to hide information about the code?

The answer is that we describe an "interface". In general, an interface is just the interaction between things. In this case, the things are the creator's class, and the user's program. If we carefully define how these things should interact, we can write it down as a specification. A specification is the description of the design of the interface.

Once the design is made, and the code its written, it would be great if we could somehow also generate the specification of the interface to the code, for our poor benighted users. The good news is that there is this awesome tool called javadoc that automatically generates a specification directly from a source file.

For this part of the lab:

  1. Download this code and save it. Take a look at it, what does it do? Open a terminal and cd to the directory that contains the file. type: javadoc Angle.java What happens? It should generate a new file called Angle.html. Open that with your web browser. You should see a description of the class. Does that match your expectations?
  2. The html is a little helpful, but if you didn't already know the source, you would still have no idea what's going on. What we need to do is annotate the source file with extra information. Read the tutorial here. Annotate the Angle class in the same way and show your instructor.
  3. Take your solution to the previous lab and move some of the methods into the classes as you think appropriate. Comment them using the javadoc tags and compile with javadoc. Show your instructor. Your instructor may go through several iterations of suggestions for methods to move around and javadoc comments to add. In the end, take a look at the html file. Could you figure out how to use your class by reading that alone? That is the goal.
  4. Reflect of the sad truth that from now on, we will require you to javadoc comment all of your programs, and we will evaluate the usefulness of the resulting html file.