Win a copy of Think Java: How to Think Like a Computer Scientist this week in the Java in General forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Frustrated Reading Java Documentation

 
Omar James
Greenhorn
Posts: 2
Chrome Eclipse IDE Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2985
12
Firefox Browser IntelliJ IDE Java Mac Ruby
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 48917
58
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Rancher
Posts: 2756
32
Eclipse IDE Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 3076
14
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2957
59
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 2
Chrome Eclipse IDE Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic