Making Your Own Documentation

If you have downloaded Java at home and looked into its directory, you will see it includes a lot of files to make the language work. The most important ones are inside the subdirectory "bin," where you will find javac.exe (the compiler), appletviewer.exe, and java.exe (which runs applications). There's another one in there called javadoc.exe, which reads through a piece of source code and then creates all the html documents necessary to make something that looks just like the API Specification--only it's for your classes. This amused me enormously once I discovered it (especially since I had been trying to imitate the html myself and it was a lot of work).

When you choose the option "Create Documentation" from the ARHS Java Editor, you are invoking a call to javadoc.exe. It will make a subdirectory named Documentation. Open up that subdirectory from My Computer and you will see lots of html files, including one called YourClass.html (or the name of the class that you are documenting). Click on that html file and you get to see your very own API Spec. Here is a screen shot of the type of thing that javadoc.exe makes for you:

Are you excited? I was! It looks real! Anyway, javadoc.exe will hunt through your code and find your fields and methods so that they can be included in the documentation. It will include only things with an access level of public or protected, since the whole point of private data members is that other programmers do not need to know about their existence.

Note: the way our editor is set up, you can make documentation either for a single class, or for a package of classes. Putting classes together into a package requires use of the keyword "package", as described here.

After you make your documentation, you will notice that it gives only the names of the fields and methods, without any description like you ordinarily find in the real API Spec. You might think that you need to type that description into the html document yourself, but you don't. Javadoc will pick up descriptions if you write comments in this form:

Notice the double asterisk right after the slash. That's what javadoc.exe will look for when it is reading through your source code. Put the descriptive line right above the place where you declare the method, field, or class that you are describing. You should also be sure to have a period at the end of the descriptive line. Javadoc.exe looks for the period as marking the end of the first sentence (even though it's not grammatically a sentence). The first sentence will appear up in the summary part of the documentation, while any additional sentences will be put in the detail section.

If you know html, then you can also insert tags into your comment and javadoc.exe will pick them up. For example, if you wanted the newRow and newColumn words to be written in code font instead of default font, you could do this:

You can also use the html tags for paragraph, bold, italics, etc..

Creating your own documentation is a good exercise because it forces you to decide if your method names really are adequately descriptive and if you have chosen the appropriate access level for your fields and methods. When you see your own class displayed on that purple and white web page, you see it more from an outsider's point of view. Would this be good enough for someone else who wanted to use my chess piece classes? Maybe someone wants to write a chess applet which has a different user interface than mine does. If my chess piece class stands on its own, then it should be just as useful for a fellow programmer as it is for me.