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
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.
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.
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
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.
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.
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....