Lesson 2.6 JavaDoc - Reading the JavaDoc Documentation
There's an old saying, you've probably heard a hundred times:
Give a man a fish and you feed him for a day. Teach a man to fish, and you feed him for his life.
Programming is a lot like that. Learning about Buttons and Labels is not nearly as important as learning how to learn about Buttons and Labels.
In Java, you can learn about all the Java classes by using the online Java Documentation, often called the JavaDocs after the program which generates the HTML help files from comments embedded in the Java source code.
Locating the Label Class
For this exercise, we're going to use the Java 2 docs contained in your JDK docs directory to see what we can find out about the Label class. The Java 1.1 docs are similar, but not identical. The JDK docs directory is not automatically installed when you install the JDK. You have to download and install the docs separately. See the Sun JDK installation site for more information.
Step 1: The JavaDoc Index Page
To start a local copy of the JDK docs, simply point Windows Explorer [the file manager] at the file index.html located in your JDK docs directory, and double-click the file.
If you'd rather work online, or you don't want to download the docs, you can go to the JavaSoft Web site and view the same documents there.
If you are working in JCreator, simply choose Help, click the JDK Help icon, or press Ctrl+F1. JCreator will display the JavaDoc help files in the IDE, so you don't have to launch a separate Web browser. To get started, choose the Java Guide tab, and double-click the index file to follow along with the rest of the lesson.
Step 2: The API Page
When you open the main JDK documentation index page, you'll find a table of contents that has links to sections on general information, the Java tools, the API and language documentation, and more.
We're interested in the API docs, so just click the API & Language link to continue on. That takes you to the middle of the page where you can select the link shown here:
|
Chan & Lee's Free Goodies
|
| At the bottom of this opening page is a link to the source code examples from Patrick Chan and Rosanne Lee's "Annotated Java Class Libraries". Even if you don't purchase the books (which are huge), the source code offered here can be invaluable. It contains small example programs for every class in the Java API. There is also a separate download for the Java 1.0 version. Do yourself a favor--grab it! |
Step 3: Finding the Package
The main JavaDoc window--which you can see below--consists of three frames:
- The Package Browser. This index appears in the upper-left corner, and consists of hyper-links to all of the Java packages. [A package is a collection of related classes.]
- The Class Browser. This index appears in the lower-left corner and consists of hyperlinks to all of the classes and interfaces in the currently selected package.
- The Content Pane. The main window appears on the right side of the screen and shown the documentation for the selected class or interface.
When you first open the JavaDoc window, the Package Browser is set to display All Classes, so every single class in the Java API appears in the Class Browser window. To show only the classes in a specific package, select that package in the Package Browser window. Normally, you'll only use the All Classes setting when you don't know in which package a particular class is located.
The class we want, java.awt.Label, is located in the java.awt package. Locate the hyperlink for that package and click on it now.
Step 4: Finding the Class
Once you've located the correct package, the Class Browser window changes to display only the contents of the package you've selected. Once you have selected a particular package the Class Browser window has [usually] four sections:
- Interfaces
- Classes
- Exceptions
- Errors
Most of the time, you won't care about the Interfaces, Exceptions, and Errors; at least until you're a little more experienced. For now, ignore them.
Find the "Classes Index" section and scroll on down until you find the class you want. In our case, we're going to look at the Label class. When you find it, click on the hyperlink.
Reading the Label Class Documentation
Finally, some meaningful information. The JavaDocs for each class are broken up into six sections. Some of these you'll find meaningful now, but others will only make sense when you are more experienced.
The six components are:
- Summary
- Inner-Class Summary
- Field Summary
- Constructor Summary
- Method Summary
- Detailed Information.
Component 1: Summary
At the very top of every class documentation page, you'll see a visual "ladder" of inheritance. As you can see, the superclass of the java.awt.Label class is the java.awt.Component class, and its superclass is java.lang.Object.
Knowing about the ancestry of a class is important because the class documentation only lists the methods and attributes that are defined in the class in question [Label in this case]. As you'll see, that's only about a half-dozen methods. Because the Label class is a child [subclass] of the Component class, however, Labels also inherit all of the methods and attributes of the Component class, and the Component class has a lot of methods.
If you want to see what some of those methods are, just click on the java.awt.Component hyperlink extending up from the java.awt.Label class.
Below the inheritance hierarchy, you'll normally find more summary information. For most classes you'll find:
- A simple explanation that tells you what the class does and, often more important, why it exists.
- A simple code example. For some of the more complex classes, the explanation is not enough; a code example is invaluable.
- A picture of the component for the basic visual classes.
Here's the remaining summary section of the Label class documentation.
Component 2: The Inner-Class Summary
Sometimes, one class may contain other classes [not objects]. These are called inner classes and they are documented in this section. We won't be working with inner classes until later in the course, so you can just ignore these for now.
Component 3: The Field Summary
As you recall, every class definition is composed of two parts: attributes and methods. Some Java classes allow you to directly access certain of their attributes. These are almost always read-only, constant values.
The Label class makes three of its fields accessible [in OO-speak we call these public class variables] so you can use them as alignment parameters with certain Label constructors.
Here is what the Fields Summary section looks like:
In your text, you might have noticed that the Font class does the same thing when it exports the BOLD, ITALIC, and PLAIN fields. With exported public variables like this, you use their values by prefacing the name with the name of the class that contain them, like this:
Label.RIGHT
or
Font.BOLD
The ALL CAPS naming convention reminds you that these are constant values. If this doesn't make a whole lot of sense to you now, don't be really concerned. You'll be using such fields throughout the course, and, over time, their use will become second nature. What's important now is that you understand how to find the information when you need it.
Component 4: Constructor Summary
As you can see below, the Label class has three constructors:
You've only used one so far, when you've created new Label objects like this:
| Label myLabel = new Label("Yowzza"); |
If you look through the index of constructors, you'll see that this looks pretty similar to the second construtor in the list, because you've passed your constructor a String just like the second example. This resemblence is called the method's signature, and it's the main technique you'll use to decide which constructor or method to call.
Take a look at the third constructor which takes two arguments instead of one. As you read the description, you can see that the second argument represents the alignment of the Label and seems to be something called an int.
Hmmm. I wonder what kind of values you'd pass to set the alignment of a Label.You've probably already made the connection: you can use the constants LEFT, RIGHT, and CENTER.
Here's how you'd use them to create a right-aligned Label :
| Label wmF = new Label("Firing Line", Label.RIGHT); |
That sort of makes sense, doesn't it. But what do you suppose, is that first Label constructor for? Why would you ever want to construct an empty Label? It's not as if you can change the text of a Label after it's created.
Or can you?
Component 5: The Method Summary
Methods, you'll remember, are the messages that an object responds to. As you can see here, a Label object can respond to seven messages. As mentioned earlier, because a Label is also a Component, it can also respond to over a hundred other messages which are defined in the Component class.
If you look though this list, you'll see that you can change the text of an empty Label after all; and maybe even the alignment. That setText() thing sounds very promising.
A little more detail wouldn't hurt, though. As you might expect, simply click on the hyperlink and you'll be taken away to Component 6 where you'll find...
Component 6: Detailed Documentation
The Constructor and Method summaries are useful for quickly finding the method that you're interested in, but many times you need more information. Here's how to get it:
- Notice that each method name is also a hyperlink. When you click the name, you'll be taken to a more extensive explanation. Try it. Click on the hyperlink for the setText(String) method, and see where it takes you.
- The detailed constructor (and method) documentation tells you what the method does and explains the purpose of each argument as you can see when you look at the documentation for setText(String) shown below.
Something to Talk About
Here are a couple exercises:
You can create a List object just like you create a Label. Instead of passing a String to your List object when you create it, however, you add Strings to the List by using its add() method like this:
List myList = new List();
myList.add("Pineapple");
myList.add("Catsup");
myList.add("Lime Jello");
Look up the documentation for the List class and see if you can find another method you could use to add text to a List. How would you create a List object and add your name to the object, using this alternative method?
In the homework assignment, you are asked to create three Color objects. Find the Color documentation and see how many different ways you can create a Color object.
This is the last section of this lesson.
|
