Re: Javadoc is not for beginners
Thomas Adrian wrote:
Hello all Java gurus.
I am in the process of learing Java, I have read a lot of books and
have made a few application and I understand a lot about how the
language works.
One thing that bothers me is the Javadoc part.
Take for instance this class:
http://java.sun.com/j2se/1.4.2/docs/api/java/net/InetAddress.html
As a beginner this page is not very informative.
- I have to scroll down to find out that this class cannot be
instantiated because there is no constructor. why can't this be more
informative, I thnk this information should be on the first line of
the HTML page. obvsiously it can't be very hard to do , right ?
Well, it *can* be instantiated, but not by the constructor
that you can't call. There are a bunch of static "factory"
methods that return InetAddress instances; that's how you can
get hold of one.
It's true that "factory" methods don't stand out in the
Javadoc the way constructors do, and this can make them a bit
difficult to find. Eventually, though, you learn to look
for them ...
And why is there never any examplecode in the javadoc
Answer #1: Sometimes there is, sometimes there isn't.
Answer #2: Javadoc is intended as a reference where someone
can check the fiddly details of something partly understood
already, not as a teaching tool or introduction to a topic.
Answer #3: Javadoc is written by programmers, and some
programmers write Java better than they write English. ;-)
Do you know any good books or webpages that explains to me how to read
the javadocs so I right away know how to implement the class I am
currently looking at in javadoc.
Sun's on-line tutorial
http://java.sun.com/docs/books/tutorial/
is a reasonable place to start. Among other things, it has
a chapter on networking (but I haven't read it and can't vouch
for its ability to teach). Give it a whirl.
--
Eric Sosman
esosman@ieee-dot-org.invalid