Lab 5: Javadoc
Up to this point, we haven't been very strict about commenting. That is because there is a right way to comment Java code.
We're heading in a direction of writing code that others can use, without them having to read your code or even understand how all of it works. As an example, we use the Java-provided Scanner class, without any idea of how it works! What are its fields? What does its constructor do with the "System.in" that we've been passing in? We don't care! When writing big code-bases, the goal is to minimize the amount of information a software engineer needs in order to use your code. Good documentation is like providing users a 'Cliff Notes' version of your source code.
That sounds great, 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 the methods of allowed interaction between two things. For example, the interface of your car is the steering wheel, the pedals, etc. A good interface gives you control of the car, once you're taught how to use it. In the case of computer code, the things interacting 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.
Take a look at this specification of the Scanner class. It's really clear! There are all sorts of descriptions of how to use a Scanner, what its methods are and what they do, a list of possible constructors, etc. You can even click on a method in order to get a more extensive description. It is really useful, but it must have taken forever! In fact, all built-in Java classes have a page like this online.
As I'm sure you've guessed, this is easier than it looks like it is. There's no way people are just sitting around coding HTML to display specifications for the entire Java language. The key is a utility called Javadoc.
Download this file, which is a version of the Mid class that we have used previously. It has been commented absurdly well. cd to the directory containing this java file, and run the command javadoc Lab5Mid.java. Use ls to see the large amount of internet files javadoc has created in your directory. Run firefox index.html and puruse the extremely helpful specification of the Lab5Mid class. Feel excitement that the power to create such files will soon be yours.
Javadoc creates the web sites by reading through the file and finding annotations. By making useful annotations, we can make useful javadoc web sites. Read the tutorial here.
The Assignment - Part I
Annotate this Lab5 Queue class so that somebody could read the javadoc web page alone, without the source code, and be able to use your class painlessly. Things to think about: does the user care about nodes? How about the private fields? What if I don't know what push means? How are peek() and pop() different? You should not submit the web pages; we can generate those ourselves. Just submit the annotated Lab5Queue.java file. It should take several minutes to familiarize yourself with the javadoc output, and several more to annotate the file. This part of the lab should take less than one period to complete. Once complete, put the modified Lab5Queue.java file into a directory named Lab05 and submit the directory. See the Resources page for complete instructions.
The Assignment - Part II
You need to use your new-found javadoc skills to annotate Project I. Open your Project I files and annotate each class. Do not submit the *.html files. We will generate them ourselves with javadoc when we grade your assignments. This annotation will be a part of your Project grade. Do not hand in your project today - just be sure that the annotation is included when you hand it in next week.
What does javadoc have to do with my life?
No doubt you are thrilled you now have the ability to write good code and explain it in the standard way to users. You will be given the opportunity to display this ability on all Labs and Projects you turn in from now on, and we will evaluate the usefulness of the resulting html file as part of your grade.