• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Frustrated Reading Java Documentation

 
Greenhorn
Posts: 2
Eclipse IDE Chrome Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Sheriff
Posts: 3063
12
Mac IntelliJ IDE Python VI Editor Java
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Marshal
Posts: 79177
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Rancher
Posts: 2759
32
Eclipse IDE Spring Tomcat Server
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Master Rancher
Posts: 4806
72
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Bartender
Posts: 3323
86
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Eclipse IDE Chrome Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
reply
    Bookmark Topic Watch Topic
  • New Topic