• 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

Making Sense of Java's API Documentation

 
Ranch Hand
Posts: 51
1
Android Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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!
 
author
Posts: 23951
142
jQuery Eclipse IDE Firefox Browser VI Editor C++ Chrome Java Linux Windows
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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...

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

Henry
 
Marshal
Posts: 79177
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 51
1
Android Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 79177
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Rancher
Posts: 4801
50
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 79177
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 51
1
Android Eclipse IDE Chrome
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 79177
377
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Remember to ask for help.
 
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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: 79177
    377
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • 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.
     
    Saloon Keeper
    Posts: 15510
    363
    • Mark post as helpful
    • send pies
      Number of slices to send:
      Optional 'thank-you' note:
    • Quote
    • Report post to moderator
    And I mostly just use them for pedantic arguments on CodeRanch :P
     
    reply
      Bookmark Topic Watch Topic
    • New Topic