Comment documentation
One of the better ideas in Java is that writing code isn’t the only important activity—documenting it is at least as important. Possibly the biggest problem with documenting code has been maintaining that documentation. If the documentation and the code are separate, it becomes a hassle to change the documentation every time you change the code. The solution seems simple: link the code to the documentation. The easiest way to do this is to put everything in the same file. To complete the picture, however, you need a special comment syntax to mark the documentation and a tool to extract those comments and put them in a useful form. This is what Java has done.
The tool to extract the comments is called javadoc, and it is part of the JDK installation. It uses some of the technology from the Java compiler to look for special comment tags that you put in your programs. It not only extracts the information marked by these tags, but it also pulls out the class name or method name that adjoins the comment. This way you can get away with the minimal amount of work to generate decent program documentation.
The output of javadoc is an HTML file that you can view with your Web browser. Thus, javadoc allows you to create and maintain a single source file and automatically generate useful documentation. Because of javadoc we have a standard for creating documentation, and it’s easy enough that we can expect or even demand documentation with all Java libraries.
In addition, you can write your own javadoc handlers, called doclets, if you want to perform special operations on the information processed by javadoc (output in a different format, for example). Doclets are introduced in Chapter 15.
What follows is only an introduction and overview of the basics of javadoc. A thorough description can be found in the JDK documentation downloadable from java.sun.com (note that this documentation doesn’t come packed with the JDK; you have to do a separate download to get it). When you unpack the documentation, look in the “tooldocs” subdirectory (or follow the “tooldocs” link).
