Get your CodeRanch badge!*
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 EJB 3 in Action this week in the EJB and other Java EE Technologies forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "Frustrated Reading Java Documentation" Watch "Frustrated Reading Java Documentation" New topic
Author

Frustrated Reading Java Documentation

Omar James
Greenhorn

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:
java.lang.Object
- org.apache.sling.api.resource.ResourceWrapper
-- com.day.cq.commons.DownloadResource
--- com.day.cq.commons.ImageResource
---- com.day.cq.wcm.foundation.Image


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
Sheriff

Joined: Oct 01, 2001
Posts: 2771
    
  10

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
Sheriff

Joined: Oct 13, 2005
Posts: 36478
    
  16
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
Bartender

Joined: Jan 17, 2008
Posts: 2052
    
  22

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: 2969
    
    9
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
Bartender

Joined: Aug 07, 2007
Posts: 1939
    
  28
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
Greenhorn

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: http://aspose.com/file-tools
 
subject: Frustrated Reading Java Documentation
 
Similar Threads
How to interpet the Java API's
Using the Random Method: How to use random numbers to represent other values?
Tapestry & JSF Comparison Tutorial
windows vs mac
difference between Driver Manager and Data Source