This is a very, very important section! The Java Application Programmer Interface (API) is a vast collection of libraries. Luckily, it is well documented, and the documentation is easily accessed using a browser starting at http://java.sun.com/docs/index.html

You can also download the html and install it locally. I prefer to download it because local access is faster than web access, and we're mostly Type A individuals in programming. However you do it, start up your favorite browser and browse the URL for the Java API for the release you installed on your computer. When the page comes up, set a bookmark for it. Your browser should be displaying something like Figure 4-1.

Figure 4-1. The API documentation

This is the standard format for the Java API documentation. There is a tool called “javadoc” that generates this HTML documentation from ordinary source code files. All the Java library code is heavily annotated with comments, which javadoc processes and displays to you (see Figure 4-1).

There are three frames in the window. Frame 1 has a scrolling list of all package names in the release. Frame 2 has an alphabetical list of all classes. Frame 3 starts off by displaying more detail on each package.

To look at a particular class, you can either click on its name in Frame 2, or if you know the package it is in, you can click on that package in Frame 1. That causes Frame 2 to display all the classes in that package. Try it now, with package java.lang. You might have to scroll the frames a bit. Then click on class “Object” in Frame 2.

That brings up all the information about class java.lang.Object in Frame 3. You will see documentation on all the methods of the class, the constructors, the error conditions it can hit, and often some more general information too.

You should get into the habit of using the javadoc documentation heavily. You should read through the API of every class described here, and every class before you use it in your own programs. You can look at the source of the run-time library, if the javadoc isn't clear enough. Repeat with each new release of the JDK. Yes, it's a lot of reading. Do it as you use each class. That's what it takes to be a highly productive programmer.

You can use javadoc on your own code and generate some HTML documentation for it. Many professional Java software suites are documented using javadoc.

Format of Javadoc comments

Javadoc is an implementation of the literate programming system invented by Donald Knuth. The javadoc tool (included with the JDK) parses source code looking for comments that start “/**”. If it finds any, it extracts them into a set of HTML pages describing the API. There are a few special tags inside a javadoc comment (they look like “@tagname”) that tell javadoc the text that follows describes a parameter, or a return value, or the author, etc. Some of the tags and the way you write them is shown in this example:

/** the API comment for HTML documentation
    @version anyLinesOfHTML
    @author anyLinesOfHTML
    @see SomeOtherClassOrMethodName
    @param anyLinesOfHTML
    @return anyLinesOfHTML
    @exception anyLinesOfHTML
    @since JDK1.1
  */

Figure 4-2. Detailed information on classes in the Java API

The javadoc comments for a class come immediately before the class. The javadoc comments describing a method come immediately before the method. You can see the formatted HTML output for the class java.lang.Object on the previous pages. Here's some of the corresponding raw source code for that class, showing the extensive javadoc comments.

/**
 * Class <code>Object</code> is the root of the class hierarchy. 
 * Every class has <code>Object</code> as a superclass. All objects, 
 * including arrays, implement the methods of this class. 
 *
 * @author  unascribed
 * @version 1.65, 12/19/03
 * @see     java.lang.Class
 * @since   JDK1.0
 */
   public class Object {
     /**
      * Creates and returns a copy of this object.
      * @return     a clone of this instance.
        *  @exception  CloneNotSupportedException  if the object's class 
        *              doesn't support <code>Cloneable</code> interface. 
      * @see java.lang.Cloneable
      */
         protected Object clone() throws CloneNotSupportedException {

Try javadoc. You can easily annotate your own code with comments javadoc recognizes. javadoc works on .java files, not .class files, because the .java files contain the comments. Add some of the javadoc tags to the clock example program and run javadoc like this:

    javadoc clock.java

or

    javadoc -source 1.5 clock.java

This will create several HTML files and a style sheet, listing the file names as it generates them. (A style sheet is an update to HTML that lets you customize the appearance of other tags. You can change colors, fonts, and sizes throughout a document by using a style sheet that overrides the default appearance).

View the javadoc output using a browser. It shows the chain of class inheritance and all the public fields in the class, along with your comments.

Whether or not you agree with the idea of using web pages to store program documentation, it offers some compelling advantages. Documentation automatically generated from the program source is much more likely to be available, accurate (what could be more accurate than the documentation and the source being two views of the same thing?), and complete (the documentation is written at the same time as the code and by the same person).