• Post Reply Bookmark Topic Watch Topic
  • New Topic

Making Sense of Java's API Documentation  RSS feed

 
Dustin Wright
Ranch Hand
Posts: 33
1
Android Chrome Eclipse IDE
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hello all,

I'm trying to learn Java to become a developer. I'm at the point where I've discovered the API documentation and I'm trying to learn to "read" it. I find I'm struggling. I've found this resource: JavaDocs. I can follow it to this point:

"Well, what you're really trying to call is something named System.out.println. If you go through the whole lookup rigmarole with Systemout, you'll find that System.out has type PrintStream. (See Figure 4, below.) So the println(String) entry you decide to choose is

println(String) - Method in class java.io.PrintStream."

I find I'm lost at this point.

The question I don't quite know how to express is, if I don't know what I'm looking for, how can I find it?

Can anyone point me to a resource to better understand the API documentation?

Thanks!
 
Henry Wong
author
Sheriff
Posts: 23295
125
C++ Chrome Eclipse IDE Firefox Browser Java jQuery Linux VI Editor Windows
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

The JavaDoc is a reference guide. And as such, assumes that you know Java. It isn't really good for learning Java -- but it is great for looking up details, once you know what to look for.


Anyway, I remember seeing a topic regarding book advice yesterday... here it is...

http://www.coderanch.com/t/657866/java/java/Advice-book-beginner-Java

Henry
 
Campbell Ritchie
Marshal
Posts: 56525
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dustin Wright wrote:. . .
println(String) - Method in class java.io.PrintStream."
. . .
You click on the link given in the documentation and see whether it takes you anywhere helpful.

Another way to do it is to look at the lower left pane and find the class System, then look for its out field (you can tell it is a field because there are no () after out), then look for its class, then go through that class for the println() method. You can tell is it a method because it has () after its name.
 
Dustin Wright
Ranch Hand
Posts: 33
1
Android Chrome Eclipse IDE
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think that's the key I'm not going to understand the documentation until I understand Java itself. I believe it's too soon.

Thanks.
 
Campbell Ritchie
Marshal
Posts: 56525
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
you should always look at the documentation in that case. Ask for help about the parts you can't understand.
 
Dave Tolls
Ranch Foreman
Posts: 3056
37
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes.
As you go through learning Java, keep the API handy so you can look up the classes used in the examples given.
That way you can look up any new methods and see what the documentation says they do. You'll quickly build an arsenal of classes etc that you use a lot.

This is a never ending thing, as you move onto other APIs etc. You should always have the relevant docs to hand so you can see what it is these things actually do.
I see too many people for whom this seems to be an alien concept.
 
Campbell Ritchie
Marshal
Posts: 56525
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dave Tolls wrote:. . . I see too many people for whom this seems to be an alien concept.
You can tell them because they are surprised when something happens they don't expect and it is exactly as described in the documentation.
 
Dustin Wright
Ranch Hand
Posts: 33
1
Android Chrome Eclipse IDE
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you all very much. I'm trying to learn Java after work, in my late 40's, in the wee hours of the morning, it's pretty slow going. I did not understand what the API documentation was until recently and now I see it for the GOLDMINE it is! I see now I don't have enough knowledge of Java to understand the API, but, the comment above is spot on, as I do exercises, I can look up the methods to better understand what they do. In the process, I'll better understand Java and the documentation.

Thank you all again for helping me understand this.
 
Campbell Ritchie
Marshal
Posts: 56525
172
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Remember to ask for help.
 
Winston Gutkowski
Bartender
Posts: 10575
66
Eclipse IDE Hibernate Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Dustin Wright wrote:I'm trying to learn Java after work, in my late 40's, in the wee hours of the morning,

Well done. Have a cow for bravery.

I did not understand what the API documentation was until recently and now I see it for the GOLDMINE it is!

Well that alone puts you ahead of many newbies.

Every Java programmer should know about the three "Biblical" web pages; which you can get to via this gateway page. And they are:
  • The Java Language Specification - often referred to as the "JLS".
  • The Java Virtual Machine Specification - usually just called the "JVM spec".
  • The API docs.
  • and of the three, that last one is definitely the one you'll use most often - especially at the beginning.

    I've been using Java for 14 years, but I rarely do any work without having it open on my desktop somewhere, and I suggest you get into the habit too. Gradually, you'll become more familiar with its structure, and how to look things up; and you'll also soon work out the difference between good and bad documentation - a very good thing to know if you want to write your own (and you will).

    I see now I don't have enough knowledge of Java to understand the API...

    Perhaps not just yet, but don't leave it too long. You don't need to know much in order to start using it - and you're quite right: it IS a goldmine.

    I don't know what experience (if any) you have with other languages, but Java is Object-Oriented; and the main difference between OO and procedural languages is that you generally DON'T need to look at code to understand how to use a class. You need to know what it does - and that is what the API documentation provides you.

    Hope it helps. And good luck in your quest.

    Winston
     
    Campbell Ritchie
    Marshal
    Posts: 56525
    172
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Winston Gutkowski wrote:. . . the three "Biblical" web pages; which you can get to via this gateway page. And they are:
  • The Java Language Specification - often referred to as the "JLS".
  • The Java Virtual Machine Specification - usually just called the "JVM spec".
  • The API docs.
  • . . .
    But beware: the JLS and JVM specification can be very difficult to understand.
     
    Stephan van Hulst
    Saloon Keeper
    Posts: 7964
    143
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    And I mostly just use them for pedantic arguments on CodeRanch :P
     
    Consider Paul's rocket mass heater.
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!