Reading and Understanding Java's API Documentation: Appendix

Appendix
Reading and Understanding Javas API Documentation

Before Java was born, people judged programming languages solely by their structural features. Does an if statement do what you expect it to do? Are looping statements easy to use? Are methods implemented efficiently? With Java, things are a bit different. Sure, Java has a whole collection of built-in language 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 at least 3,000 canned programs, each with its own functionality, its own limitations, and its own rules for effective use. How do you figure out how to use all these programs? The answer is, you dont. You figure out how to use a few, and you read Javas API documentation. With this documentation, you can find information you need, when you need it.
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 instance, in many of this books listings, I call a method named System.out.println. The rest of this appendix describes two ways to look up the System.out.println method.
Using the index

Heres how to find something, such as System.out.println, by using the index: 1. Download Suns Java API documentation. For more help on downloading the documentation, see Chapter 2. 2. Open to the front page of the documentation.
When you download the documentation, you get several directories. In the top-level directory is a file named index.html (or index.htm). Open this file in your Web browser. 3. Click the API & Language link, which is near the top of the front page, as shown in Figure A-1. This takes you farther down on the same Web page.
Figure A-1: The front page of Suns documentation.

Copyright 2004 Sun Microsystems, Inc. Reprinted with permission.
4. Click the Java 2 Platform API Specification link, as shown in Figure A-2. The browser transports you to the start of the API pages, which are shown in Figure A-3.
Figure A-2: A link to the API specification.

Figure A-3: The start of the documentations API pages.

5. Click the Index link at the top of the page to open the index, as shown in Figure A-4. A list of letters is near the top of the index. Click the P link to go to the section with println in it.
Figure A-4: The API documentations index.

6. 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. Heres how:
A. 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. (Dont click a link. Click on some neutral white area of the frame.) B. Open the browsers Find dialog box. On most browsers, pressing Ctrl+F coaxes the Find dialog box out of hiding. C. When you see the Find dialog box, type println in the text box and click the boxs Find or Find Next button. 7. Pick one of the println entries. The P section has a big boatload of println entries, as shown in Figure A-5. 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.
Figure A-5: Some println entries in the API documentations index.

At this point, it pays to poke around. If youre trying to print something like "Hello world!" , you want one of the println(String) entries. On the other hand, if youre trying to print the value of amountInAccount, youll probably choose a println(double) entry. Now, suppose youve decided on println(String). You can choose from three println(String) entries. One says its a method in class java.io.PrintStream, the next is a method in class java.io.PrintWriter, and the third is a method in class java.sql.DriverManager. Which of these three entries do you choose? Well, what youre really trying to call is something named System.out.println . If you go through the whole lookup rigmarole with System.out, youll find that System.out has type PrintStream. (See Figure A-6.) So the entry you decide to choose is println(String) - Method in class java.io.PrintStream.
Figure A-6: The out variable has type PrintStream.

8. Click the link for the entry that youve chosen. When you click the println(String) link, the browser takes you to a page that explains a println method, as shown in Figure A-7. 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.
Figure A-7: A description of the println method.

Using the list of classes

Heres how to find an entry in the API by starting in the list of classes: 1. Navigate to the start of the documentations API pages. To do this, follow the first four steps in this appendixs Using the index section. 2. Find the page that documents the System class. Youre 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 A-8.) For hints on finding text on the page, see Step 6 in the Using the index section.
Figure A-8: 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 A-9.
Figure A-9: The System classs documentation.

3. On the documentation page for the System class, find the out variable. If you use your Web browsers Find dialog box, you have to click the Find Next button several times. (The word out is so common, it appears several times in several different contexts on the System documentation page.) When youve found what youre looking for, you see a table like the one shown in Figure A-6. 4. In the tables 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. Thats why youre clicking the PrintStream link. 5. On the documentation page for PrintStream, find println(String). You see an explanation like the one shown in Figure A-7.
You Can Do It Too

After following the steps in this appendix, you may be tempted to say, Big deal, I can find println in the API docs, but I probably cant find anything else. And if people create documentation for stuff that they program on their own, then their documentation wont look like the standard API documentation. Ill be up a creek. My response to all this is Nonsense! Heres why: * Most of the tricks you need for finding things in the standard Java documentation are illustrated in this appendixs step-by-step instructions. If you can find System.out.println, you can also find javax.swing.JButton or any of the 3,000 programs in the standard Java API. And, as you discover more about Java and the relationships among classes, methods, and variables, this appendixs step-by-step instructions will feel much more natural. * As for reading other peoples documentation, you can scratch that problem right off your list. The standard API docs werent typed by hand. They were generated automatically from actual Java program code. For instance, the code for PrintStream.java 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 folks from Sun Microsystems ran a program called javadoc. The javadoc program took lines like these right out of the PrintStream.java file and used the lines to make the documentation that you see in your Web browser. Other Java programmers -- people who dont work for Sun Microsystems -- do the same thing. In fact, everyone who writes Java code uses the javadoc program to generate documentation. So everyones Java documentation looks like everyone elses Java documentation. When you know how read to the standard API documentation, you know how to read anybodys homegrown Java docs. And yes, you can use the javadoc program too. When you download the JDK (see Chapter 2 for the details), you get the javadoc program as part of the deal. To find out more about turning your program comments into Web pages, visit this books Web site.

Reading and Understanding Java's API Documentation: Appendix

Uploaded by

Copyright:

Available Formats

Reading and Understanding Java's API Documentation: Appendix

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Reading and Understanding Java's API Documentation: Appendix

Uploaded by

Copyright:

Available Formats

Appendix

Reading and Understanding Javas API Documentation

Searching for a Term

Using the index

Figure A-1: The front page of Suns documentation.

Figure A-2: A link to the API specification.

Figure A-3: The start of the documentations API pages.

Figure A-4: The API documentations index.

Figure A-5: Some println entries in the API documentations index.

Figure A-6: The out variable has type PrintStream.

Figure A-7: A description of the println method.

Using the list of classes

Figure A-8: Finding a link to the System class.

Figure A-9: The System classs documentation.

You Can Do It Too

* and then <code>{@link #println()}</code>. * * @param x The <code>String</code> to be printed. */

You might also like