API Docs

Finally, some tips for working with the docs.

Remember that you can search for words in IE by pushing the Control key + F. This is especially useful in the docs index, in which a single page can be very large.

Remember that if you think a class should do something, there are standard names for most operations and you can usually guess what a method will be called - 'setVariable' and 'getVariable' for example. Others start 'index' (for list objects), 'equals' (for comparisons), 'to' (for casting methods), 'add', 'remove' and 'is' (for windows based operations). We'll see these and more naming standards as the course progresses.

If you can't find a method or variable you expect to find in a class, check out the list of methods inherited from all the superclasses above it - it's probably in there.

If a method takes in an int to set something, rather than as part of a mathematical operation, it probably won't say what specific value it's after. So, for example, the 'java.awt.Label' object, which lets you display a line of text on the screen in a windows environment, takes in an int into one of its constructors.

It's apparent from the name of the int that it effects the text alignment. If you look at the constants (fields/static final variables) that Label has in it you can see it has three int value constants - CENTER, LEFT and RIGHT. If you look at the more detailed docs for Label later, you'll see that these are the int values expected by the constructor in question.

It doesn't actually matter what the values of these constants are - you just use them in the constructor, that way it becomes obvious to people reading your code what you're doing. Thus...

Label peachLabel = new Label("Peach", Label.RIGHT);

...is more obvious than...

Label peachLabel = new Label("Peach", 2);

Note that because the constants are inside the Label class you need to call them using the class name. Because they are 'static' (see the screenshot above) you don't need to make a Label object first, you can call them straight from the Label class - in this case using Label.RIGHT - static constants are one case where you don't use objectName.getVariable().

Finally, remember that these docs are produced in exactly the same way as you produce docs for your programs. You should aim to make your documentation just as informative (more so in the case of some API classes!).

That's it for this tutorial. Now you know your way around the API docs, have an explore, and think through what is useful, and would be useful in terms of your own code. If you haven't looked at it yet, check out the tutorial on writing your own docs.