File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Beginning Java and the fly likes Frustrated Reading Java Documentation Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Java Interview Guide this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Frustrated Reading Java Documentation" Watch "Frustrated Reading Java Documentation" New topic

Frustrated Reading Java Documentation

Omar James

Joined: Jan 03, 2013
Posts: 2

I'm an experienced programmer mostly UNIX shell/PERL scripting. I do OK programming in Java (basic stuff) the issue comes when I need to use a non-standard or non-highly used package/API (for lack of a better description). I can't seem to understand the documentation on it. Are there points to start at and then read down so that I can understand how to use the subclasses..... I've been very frustrated about this from the get go....

Example of what I'm referring to:

I'm not asking for tutorial on the classes mentioned above, I'm asking for tips or better yet a tutorial on how to understand Java Documentation.
Greg Charles

Joined: Oct 01, 2001
Posts: 2969

Hi Omar, welcome to JavaRanch!

That appears to be a class hierarchy. Do you understand the concept of inheritance? That's really the key to understanding this documentation, and to being a good Java programer.
Campbell Ritchie

Joined: Oct 13, 2005
Posts: 46437
You can tell a lot from that little paragraph. Not only can you tell that Image extends ImageResource, and that extends …
but you can also tell from the name of the packages that the ResourceWrapper is an Apache creation, in their sling project, etc., and that somebody called Day (or a company called Day) extended it to create the Image class. You can tell that from the package names, and knowing about package name conventions.
Jayesh A Lalwani
Saloon Keeper

Joined: Jan 17, 2008
Posts: 2749

Usually, when you are learning a new API, the Javadocs are not a good place to start. I would start from a tutorial.

JavaDocs are for reference. That is when you know that a particular API can be used to do something, but you don't remember how exactly to do it, you can look it up in the API.

Think of Javadocs as a thesauraus/dictionary. You don't learn how to write in a particular language by reading the dictionary. You learn it by understanding the grammar. Once you get a handle of how the language works, you learn new words or find related words, you use the dictionary/thesauraus
Mike Simmons
Ranch Hand

Joined: Mar 05, 2008
Posts: 3028
Jayesh A Lalwani wrote:Usually, when you are learning a new API, the Javadocs are not a good place to start. I would start from a tutorial.

That sounds a little extreme to me - for me, the API is my first stop when looking to understand something new. Often, that's all I need. Sometimes, however, they do a very poor job, in which case yes I agree that you should look for a tutorial instead. It depends on the project and who did it. Typically APIs from Sun/Oracle are pretty well done, whereas APIs from open-source projects are often lacking. Anyway though, I would say: don't hesitate to check out the API first, and if it's opaque or lacking, don't hesitate to look for a tutorial instead.
Tony Docherty

Joined: Aug 07, 2007
Posts: 2839
Mike Simmons wrote:That sounds a little extreme to me - for me, the API is my first stop when looking to understand something new.

I think it depends greatly on what you are looking for. If you are building on existing knowledge then the API is great, but if you have absolutely no knowledge and it's not a simple single class solution then generally a tutorial is better.
For instance, if you already know how to use Streams but don't know which classes to use for a particular task then the API docs are ideal. But if you have no idea how to use Streams or it's a complex problem like implementing Drag and Drop support then a tutorial is definitely the place to start.

Omar James

Joined: Jan 03, 2013
Posts: 2

Greg - I do understand inheritance and I get how one extends the other.
I have seen how some classes are very well documented but I guess now I've confirmed what I didn't want to accept. That is even though the classes are written by a reputable company, it doesn't mean they are well documented. In my case, there is a lack of tutorials or sample code on what I'm trying to do and that's what led me to looking at Docs....

Thanks to everyone for prompt responses.
I agree. Here's the link:
subject: Frustrated Reading Java Documentation
It's not a secret anymore!