Finding my way around the API docs

[Glen Ihrig]

Hello all,

This is my first post to Java Ranch, and frankly I don't understand why this question doesn't get asked a LOT, maybe I have missed something BIG...


How the **** do you guys find your way around the Java API Docs?


Maybe I'm just totally spoiled by other languages' docs, but it seems to me that if I want a class to perform a basic programming function, I should be able to search for the _general_function_ and find a list of applicable classes.

Examples:
Referring to the "JDK 5.0 Documentation" in HtmlHelp format from http://www.allimant.org/javadoc/index.php

1. Suppose I want to build a string from a bunch of fragments - I've been told that "abc" + " " + "xyz" is evil...

"Concatenation of localized strings to produce a longer string is not valid because the word order changes from one locale to the next."

The recommended alternative from this source is "Use the class Message to construct the string..."

A search for "Message" returns a bunch of stuff, but no classes by that name...

A search for the logical "concatenation" returns one entry for "concatenateTransform" (what ever that is - docs go way over my head).

A search for "String" returns a _large_ number of results, none of which mention concatenation. Searching the entry for class "String" finally reveals this:

"String concatenation is implemented through the StringBuilder(or StringBuffer) class and its append method."

But the "append" method is not mentioned further..

Finally, after several hours of frustration and much googling, I discover that the advice I had was in error. The class that assembles locale friendly strings is "MessageFormat".

2. Suppose I want to know about the various Java data types and their memory requirements?

3. The String class has a lot of functionality but apparently converting a string to Title Case is not among them. At least a search within the String class entry for "title case" returns nothing and "case" finds a bunch of entries relating upperCase, lowerCase and caseInsensitve.

The point is, over the last 25 years, I have worked with a variety of languages from 6803 ASM to various flavors of Basic, Pascal, DBase, ColdFusion and PHP. After working my way through "Head First Java", "Head First OOA&D" and working on "Head First Design Patterns", I feel that the API docs represent my steepest learning curve.

I have reviewed the recommendations at http://faq.javaranch.com/view?JavaApiDocs, but these don't provide much help.

Books:

"Java Almanac" looks good, but is rather out of date.
"Java In A Nutshell" appears to be largely a printed copy of Sun's API docs.

I have learned Java (to some extent), so now how do I quickly find my way around the API?


Thanks for any suggestions.

-Glen
[ March 15, 2007: Message edited by: Glen Ihrig ]

[Michael Dunn]

a number of IDE's link their 'Help' to the api docs.
you highlight, or type in, a method name and all classes
with that method name are listed.

[marc weber]

Welcome to JavaRanch!

Now I'm confused. I've never seen the documentation you reference from allimant.org. Is this what you're using to search the API?

Your quote, "Concatenation of localized strings...," seems to be from instantiations.com. Is this a third-party product you're using?

Have you tried Sun's API (Java 6)? There are different ways to use this, but I usually just use the browser's "find" feature in the lower left frame (All Classes).

With respect to the append method, when the API for the String class says, "String concatenation is implemented through the StringBuilder (or StringBuffer) class and its append method," this means that you will find the append method documented under the StringBuilder (or StringBuffer) class. You will not see "append" mentioned further in the String class because Java Strings are immutable.

[Paul Clapham]

It's easier than you think. But first: I went to that site you linked to and it didn't have the API documentation in it. It wanted me to download it. I didn't want to do a multi-megabyte download of something just to answer a question here. So bear in mind that I don't know what features it has. Everybody else seems to use Sun's documentation which you can find here:

http://java.sun.com/j2se/1.5.0/docs/api/

(I usually turn off the frames because they just get in the way of searching with Control-F in my browser.)

It's got an index, so if you think you know a method name then you can look that up in the index. Searching for part of the method name might be a useful feature, but when there are over 5,000 classes in the API it could easily overload you with results. (The number of classes is part of the reason it's so daunting.)

1. Of course it's hard to search when you are told the wrong thing in the first place. You would never have found MessageFormat by randomly looking about. But that isn't the fault of the documentation, it's the fault of whoever told you that. And now that you know about it, did the API documentation tell you what you needed to know?

2. Sizes of Java objects is one of those things that beginners think they have to worry about. It generally isn't possible to say how much memory an object of a particular class will take, so that information isn't in the documentation.

3. You did that right too. You just didn't draw the right conclusion: if it isn't in the documentation then it doesn't exist. There really isn't a method to produce a title-case version of a String. Admittedly it's hard to know when to draw that conclusion; after all maybe you missed it, or maybe Java calls that something else and you went right by it, and so on.


As for "quickly", that's something that comes with practice. I have a downloaded copy of the documentation on my computer so I don't need to go to the Web all the time to look at it.

[marc weber]

Paul already addressed the size of Java objects above. The sizes of Java's primitive types are specified in the Java Language Specification (JLS), which is another reference you might want to bookmark. In particular, see JLS - 4.2 Primitive Types and Values.

As Paul also mentioned, getting acquainted with the API really comes with practice. When I first saw the Java API, I was overwhelmed, and had the same reaction I think you're having: "There must be another way." But after digging in, it didn't take long before I got comfortable with it, and now I quite like it. In fact, I've been disappointed that some other languages (C#, LotusScript, JavaScript...) aren't documented like Java. So I know how frustrating it can be when you need to find something and keep hitting brick walls, but a lot of that just depends on what you're used to.

Now that you've found the JavaRanch community, your coding life should get a lot easier!
[ March 15, 2007: Message edited by: marc weber ]

[Glen Ihrig]

Wow!,

First of all thanks for all the helpful input - A great first impression of Java Ranch.

@Michael Dunn

a number of IDE's link their 'Help' to the api docs.

I'm using Eclipse and this feature (F2) is often helpful when reviewing existing code. I'd never thought to just type in my best guess to see what it turned up.

I played around with this a bit and it is useful. I can see making more use of this feature as I get to know the API, right now I'm just trying to get my wits around what's available.


@Mark Webber

I learned about the docs on http://allimant.org./javadoc/ from Google, I think. It's the Sun API repackaged in Windows HtmlHelp format. I often find that HtmlHelp is easier to search than html docs, but that's just a preference. It's that same API as can be found on Sun's site.

I guess mentioning this qualifies as a "red herring", my apologies for that.

Your quote, "Concatenation of localized strings...," seems to be from instantiations.com.

I guess you win the product trivia prize Yes that information is from Instantiations' CodePro product.

Have you tried Sun's API?

Yes, but that's what got me overwhelmed in the first place, not that the same data packaged in HtmlHelp format is really any different. I'm just having difficulty finding what I need, when I don't know what to call it.


@Paul Clapham

You're right, http://allimant.org./javadoc/ is a resource to be down loaded for those who prefer Windows HtmlHelp format - _please_ don't download all that data on my behalf, it's the same data provided by Sun, just repackaged. I really should not have mentioned that site as it only confused my request.

but when there are over 5,000 classes in the API it could easily overload you with results. (The number of classes is part of the reason it's so daunting.)

That is exactly the problem. What I was hoping to find was some kind of cross reference, kind of like a table of contents to this voluminous sea of data. I suppose you could argue that the class names themselves are sort of a contents list, I just don't know them well enough yet.


@All

So, It seems the bottom line is that Java has a sort of a surprise twist in the learning curve for beginners. Just learning the language is not enough, then You have to learn the APIs as well, and that can be quite overwhelming for the rank beginner. But not to fear, you'll get it in time...

Am I correct then in believing that those who have posted above have found the API docs to be pretty much all that is needed?

You don't use books like "Java Almanac" or "Java In a Nutshell"? Did you find these, or similar titles useful in learning the API?

Head First Java (pg 158-159) recommends using Java In a Nutshell to locate the class you need, then finding the details in the official API docs. I am a little hesitant to spend ~$30 for a copy of the APIs unless it's really going to help me learn what I am unable to learn by browsing the API docs. I guess I need to visit the _real_ book store and have a look for myself.

Thanks again for all your input, this has been a real concern for me. Knowing that I'm on the right track and just need to keep going has been very encouraging, even if I still don't know my String from a MessageFormat

-Glen

[Michael Dunn]

> You don't use books like "Java Almanac" or "Java In a Nutshell"?

When I first started in java I bought Java Almanac, and Java Programmers
Reference, just for working code examples.

These days I use the search functions here/sun/google etc searching for
"new [ClassName]"
and it generally produces a wealth of working examples.

[Alex van der Hoek]

At the risk it might look as a bump post, i'll use my firt at The Big Moose saloon as a reply to the question (and the answer) i was looking for in the first place.
Bought the Java Nutshell series incl. Examples2 back in 2000, but never got around to spend the time needed to get to grips with Java. Now i've reached a point where i need to get serious about it, so decided to go for the SCJP.
The execllent K&B book somehow linked me to the JavaRanch, and what a treasure this is.
Back to the question at hand. Now that i've found the anwser i just want to add, i did use the Foundation Classes in a Nutshell but my version covers up until 1.3, whereas i want to take the 1.5 SCJP test. And i also don't really want to spend another �35 on an updated version if the info is at hand in Ecplise or at Sun. So thanks all for asking AND answering this question.
Time for some Java, milk and 1 sugar please....