How do i read java documentation?

Question

I'm looking for some advice on how to go about reading the online documentation of various packages classes and methods for java.

i mean all this stuff: http://java.sun.com/javase/6/docs/api/

Answer 1

Read it as needed. As in, in the context of a project. Documentation is largely a need based format, not a concepts teaching format.

Otherwise, if you want to actually read something to learn the SDK for example, read a teaching book.

Answer 2

The JavaDoc is merely a references. It's great for answering a question of the form "what does this (class / method) do?" but is terrible for just about anything else.

If you're confused by the JavaDoc, you should pick up a book or find an online tutorial. Use the documentation as a reference to answer specific questions only, and maybe you won't be as confused.

Answer 3

Here's a tutorial.

And indeed, read it only when needed. For the remnant, go through a tutorial. Usually Googling "[keyword] tutorial site:sun.com" yields enough results.

Update to take the following as an example for which you'd like to find the Javadoc:

someString.split("\\.");

Here someString is an instance of java.lang.String. Assuming that you'd like to start up from the API documentation root (I myself rather prefer to type just "java.lang.string javase api site:sun.com" in Firefox's address bar to get it straight for me (if you feel lucky and didn't already have it in browser history), or to just check it in my IDE), then scroll in the main frame to the java.lang package and click the link, then in the class summary check the String class and click the link, then in the method summary check the split() method and click the link.

The Javadoc of the Java SE API is concise, but pretty complete and provides links to other javadocs where you expect them to be. For example, at the bottom of the String#split() javadoc you see a "See Also" link to the Pattern class, which in turn explains that regex stuff in the class' introduction.

Answer 4

Imagine that you have a String, and you're trying to work out how to convert it to uppercase. Look at the javadoc for String, at http://java.sun.com/javase/6/docs/api/java/lang/String.html (or from your link above, just scroll down to find String in the lower left list.

You'll find there's a method there called toUpperCase(). You can click on it to find the details. And you'll see all the other methods there, that describe the sorts of things you can "do" to a String.

And there's a list of constructors as well, which tell you how you can "create" a string object.

Maybe it's not too hard for a String, so try something more complex: How do you create a BufferedOutputStream?

Answer 5

Imagine the javadoc as browsing albums in itunes. The top left frame is a list of packages. Thats like a list of artists. Selecting one of those changes what is shown in the bottom left frame. The bottom left frame is a list of Classes/Interfaces in the package selected above it. Thats like selecting an artist and showing the list of albums. You can then select one of the classes/interfaces and a detailed view of it will appear in the main frame. Thats like the track list for the selected album.

ITunes analogy aside, the main frame details show all of the public and protected information needed to interact with that class or interface. At the top it shows the inheritance hierarchy, and a description of the class. Below that is a summary of all the fields, constructors, and methods that are public or protected on the class. You can click a link on any of those to jump to a full description. At the bottom of the summary is a list of all the inherited methods.

Any classes that are referenced in a javadoc such as argument or return types will be links. If you click the link, it will navigate to the javadoc for that class. In this way is is pretty easy to navigate through all of the classes needed to figure out what is going on. It isn't exactly pretty, but it works. Being html, you can even open links in a new tab, and therefore easily open all related classes at once.

One last tip - there are some extra options at the top of the detail pane. One that I use a lot are the Frames/No Frames links. This will add or remove the package and class frames on the left. If you open other classes in new tabs, or sometimes if you find a class using google, you will wind up on a page with no extra frames. Just click the Frames tag and they'll get added to the page.

Answer 6

The most helpful thing for me learning the Java SE APIs was to do "The Java Tutorials". It covers pretty much the whole of Java SE, in a much more organised manner than the JavaDocs. After you read the bits you're interested in, the JavaDocs will make more sense on their own.

Usually I read the JavaDocs for bits I'm interested in through the IDE. I use Netbeans, which automatically displays JavaDoc as part of its code-completion. That way, I can partially type a class or method name that I'm thinking of using, and then browse through the JavaDocs of the suggestions until I find what I want.