Making Sense of Java's API Documentation - dummies

By Barry Burd

Once upon a time, people judged programming languages (including Java) solely by their grammatical features. Does an if statement do what you expect it to do? Are looping statements easy to use? Are methods implemented efficiently?

Nowadays, things are a bit different. Java has a whole collection of grammatical features, but Java is much more than just a big set of grammar rules. Java has a standard Application Programming Interface —a huge library consisting of over 4,000 classes, each with its own functionality, its own limitations, and its own rules for effective use.

Searching for a term

You can find things in the API documentation in a number of different ways. Each way is convenient in one situation or another. For example, Java has a method named System.out.println. What follows describes two ways to look up the System.out.println method.

Using the index

Here’s how to find something, such as System.out.println, by using the index:

  1. Visit

  2. Click the INDEX link at the top of the page to open the index, as shown in Figure 1.

    Figure 1: The API documentation's main page.
    Figure 1: The API documentation’s main page.

    A list of letters is near the top of the index (see Figure 2). Click the P link to go to the section with println in it.

    Figure 2: The API documentation’s index page.
  3. In the P section, do a search for println to find the println entries.

    Most web browsers enable you to search for something like println in the text of a page. Here’s how:

    1. Make sure the browser knows that you want to search in the big frame that takes up most of the page (and not in the smaller frames on the left side of the page). To do this, click your mouse inside the big frame. (Don’t click a link. Click on some neutral white area of the frame.)

    2. Open the browser’s Find dialog box. On most Windows browsers, pressing Ctrl+F coaxes the Find dialog box out of hiding. On a Mac, clicking Command+F does the trick.

    3. When you see the Find dialog box, type println in the text box and click the box’s Find or Find Next button.

  4. Pick one of the println entries.

    The P section has a big boatload of println entries, as shown in Figure 3, below. The entries differ from one another in two ways:

    • Each entry says println(int), println(String), or println(someOtherTypeName). The type name can differ from one entry to another.

    • Each entry says that println is a method in class java.someStuff.someMoreStuff. The class can differ from one entry to another.

      println entries in the API documentation’s index.”/>
      Figure 3: Some println entries in the API documentation’s index.

    At this point, it pays to poke around. If you’re trying to print something like “Hello world!”, you want one of the println(String) entries. On the other hand, if you’re trying to print the value of lengthOfStraightLine, you’ll probably choose a println(double) entry.

    Now, suppose you’ve decided on println(String). You can choose from three println(String) entries. One says it’s a method in class, the next is a method in class, and the third is a method in class java.sql.DriverManager. Which of these three entries do you choose?

    Well, what you’re really trying to call is something named System.out.println. If you go through the whole lookup rigmarole with Systemout, you’ll find that System.out has type PrintStream. (See Figure 4, below.) So the println(String) entry you decide to choose is

    println(String) – Method in class

    out variable has type PrintStream.”/>
    Figure 4: The out variable has type PrintStream.
  5. Click the link for the entry that you’ve chosen.

    When you click the println(String) link, the browser takes you to a page that explains a println method, as shown in Figure 5. The page tells you what println does (“Print a String and then. . . .”) and points to other useful pages, like the page with the documentation for String.

    println method.”/>
    Figure 5: A description of the println method.

Using the list of classes

Here’s how to find an entry in the API by starting in the list of classes:

  1. Visit

  2. Find the page that documents the System class.

    You’re looking for documentation that explains System.out.println. So you look up System, work your way to out, and from there, work your way to println.

    To find a link to System, look in the lower frame on the left side of the page. (See Figure 6.) For hints on finding text on the page, see Step 3 in the “Using the index” section.

    System class.”/>
    Figure 6: Finding a link to the System class.

    Clicking the System link makes your browser display the documentation page for the System class, as shown in Figure 7.

    System class’s documentation.”/>
    Figure 7: The System class’s documentation.
  3. On the documentation page for the System class, find the out variable.

    If you use your web browser’s Find dialog box, you have to click the Find Next button several times. (The name out is so common, it appears several times in several different contexts on the System documentation page.) When you’ve found what you’re looking for, you see a table like the one shown in Figure 4, above.

  4. In the table’s out row, click the PrintStream link.

    According to the documentation, the out variable refers to an object of type PrintStream. This means that println is part of the PrintStream class. That’s why you’re clicking the PrintStream link.

  5. On the documentation page for PrintStream, find println(String).

    You see an explanation like the one shown in Figure 5, above.

You can do it, too

After following the steps in this article, you may be tempted to say, “Big deal! I can find println in the API docs, but I probably can’t find anything else. And if people create documentation for stuff that they program on their own, then their documentation won’t look like the standard API documentation. I’ll be up a creek.”

The appropriate response to such an objection is “Nonsense! Baloney! Balderdash! Horse feathers!” Here’s why:

  • Most of the tricks you need for finding things in the standard Java documentation are illustrated in this article’s step-by-step instructions. If you can find System.out.println, you can also find javax.swing.JButton or any of the 4,200 programs in the standard Java API.

    And, as you discover more about Java and the relationships among classes, methods, and variables, this article’s step-by-step instructions will feel much more natural.

  • As for reading other people’s documentation, you can scratch that problem right off your list. The standard API docs weren’t typed by hand. They were generated automatically from actual Java program code. For example, the code for has a few lines that look something like this:

    *    Print a String and then terminate the line.
    *    This method behaves as though it invokes
    *    <code>{@link #print(String)}</code> 
    *    and then <code>{@link #println()}</code>. 
    *    @param x   The <code>String</code> to be printed.

    To create the API documentation, the captains of Java ran a program called javadoc. The javadoc program took lines like these right out of the file and used the lines to make the documentation that you see in your web browser.

    Other Java programmers do the same thing. In fact, everyone who writes Java code uses the javadoc program to generate documentation. So everyone’s Java documentation looks like everyone else’s Java documentation. When you know how read to the standard API documentation, you know how to read anybody’s homegrown Java docs.

    And yes, you can use the javadoc program to create your own documentation. When you download the JDK, you get the javadoc program as part of the deal.