Javadoc is not for beginners

Javadoc is not for beginners

Post by Thomas Adr » Sun, 18 Nov 2007 20:33:40

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:

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 ?

And why is there never any examplecode in the javadoc

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.


Javadoc is not for beginners

Post by Patricia S » Sun, 18 Nov 2007 20:51:03

Javadocs are definitely reference, not tutorial, material. Also, like
most of Java, they tend to improve with time. I suggest working with a
more recent version than 1.4.2.

If you are learning about an area, such as Java networking, begin with a
tutorial or book about that area. Look to get the broad picture of how
things fit together from that, but precise details from the javadocs.



Javadoc is not for beginners

Post by Andrew Tho » Sun, 18 Nov 2007 21:37:24


Besides what Patricia was saying, but following your
example of 1.4.2.

Getting a concrete instance or object of what you need,
can sometimes be tricky.

Make sure you check the 'Use' link listed at the top of
the page, this anchor shows a bunch of methods that
return an InetAddress

Sometimes the generic class will not offer constructors
because it is (for whatever reason) abstract, and leaves
the concrete implementation to a sub-class (or
sub-sub-class etc..). So be sure to chase the links to
'Direct Known Subclasses:' (until they run out). For this
class, the DKS are listed as InetAddress4 and InetAddress6.

Also, check the methods starting with 'get' for anything
< #method_summary

In this case, all these seem to return an InetAddress
or InetAddress[].

getAllByName(String host)
getByAddress(byte[] address)
getByAddress(String host, byte[] address)
getByName(String host)


Andrew Thompson

Message posted via

Javadoc is not for beginners

Post by Eric Sosma » Mon, 19 Nov 2007 00:17:31

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

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

Sun's on-line 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

Javadoc is not for beginners

Post by Hunter Gra » Mon, 19 Nov 2007 01:32:15

That does not excuse you from reading it.

Javadoc is not for beginners

Post by Mark Spac » Mon, 19 Nov 2007 10:57:18

Nevertheless you should keep reading those Javadoc pages. I had a lot
of trouble reading the Javadoc too when I first started. As one gets
more familiar with the Java API, it gets easier to understand what's
being presented. Right now, I always consult the Javadoc first, because
80% of the time it'll answer any question I have.

If you can't understand the Javdoc after trying, Google for the
classname plus the words "java tutorial":

That's the first link I get when I Google for "InetAddress java
tutorial". It's not perfect, but it's in the right section. Going "up"
one to the tutorial TOC will get you a bunch of introductory stuff on
networking and InetAddress.

Good luck.

Javadoc is not for beginners

Post by Thomas Adr » Mon, 19 Nov 2007 17:56:49

Thank you all for replying,

- If javadoc is just a reference, it should be renamed to javaref
- My point here is that it is very difficult to understand how to
implement certain classes by just lookung at the javadoc.
- Javadoc is based on what the developer choose to include in the
sourcecode, So Sun should really concider improving the javadoc and
make it more userfriendly. It could be made much better by just
including a few statement on the top of the javadoc page.
- Really, how many of you do not google the class you are about to
implement ?
- A lot of classes out there is not made by Sun , so they may not be

- Thomas

Javadoc is not for beginners

Post by Roedy Gree » Mon, 19 Nov 2007 18:25:14

On Sat, 17 Nov 2007 03:33:40 -0800 (PST), Thomas Adrian
< XXXX@XXXXX.COM > wrote, quoted or indirectly quoted someone who
said :

The problem is mainly that the people who write Javadoc have just
finished implementing the method. Therefore what it does is far too
obvious to them. They should write it BEFORE, or somebody else should
write it, asking questions of the implementor.
Roedy Green Canadian Mind Products
The Java Glossary

Javadoc is not for beginners

Post by Roedy Gree » Mon, 19 Nov 2007 18:26:56

On Sat, 17 Nov 2007 03:33:40 -0800 (PST), Thomas Adrian
< XXXX@XXXXX.COM > wrote, quoted or indirectly quoted someone who
said :

I think of JavaDoc as jog-your-memory notes. To understand a method I
nearly always have to read the source. When I get the hang of it, then
I can make sense of the Javadoc shorthand.
Roedy Green Canadian Mind Products
The Java Glossary

Javadoc is not for beginners

Post by Patricia S » Tue, 20 Nov 2007 00:31:47

The sequence I like when I'm programming is to write unit tests and
Javadocs in parallel, followed by the code.

Unit test writing encourages thinking about edge cases. Is it OK for
this parameter to be null, and if so what happens? If it is done in
parallel with Javadoc writing, the single decision feeds immediately
into the documentation.


Javadoc is not for beginners

Post by Lew » Tue, 20 Nov 2007 01:27:18

And thank you for not top-posting in the future. Use trim-and-inline posting.

If it's just a way of documenting Java code, it seems like "Javadoc" is a
clever and appropriate name.

That's why there are so many tutorials and books and articles out there.

And there are - they're all over the Javadocs, as are package summaries.

I don't. I usually just use the Javadocs.

Do you write your own Javadocs to the standard you espouse?


Javadoc is not for beginners

Post by Joshua Cra » Tue, 20 Nov 2007 05:55:22

It's an automatic documentation generator for Java; doc is a
commonly-accepted abbreviation for documentation, and the concatenation
of Java and doc is Javadoc, hence the origin of its name.

Implement or use? The purpose of the documentation is to provide
specific, per-instance detailed semantics of classes, methods, packages,
etc. These are the reasons when I use the Javadoc APIs, roughly ordered
by how often I use them for that reason:

1. What is the signature of method XYZ?
2. How do I use class XYZ to do foobar?
3. Can class XYZ do foobar?
4. Which package is class XYZ in? (I am ashamed to admit this...)
5. What can class XYZ do?

If you think that Javadoc is hard to understand, try reading some of the
Windows API documentation or Linux man pages for libraries or functions.
I have seen points where the only documentation was to look at the code
and figure out what exactly it was doing. Annoying when you're trying to
figure out whether or not you have to free a char* you pass in.

Sun's Java APIs are amazingly well-detailed, much more so than some of
the other documentations I've come across. In addition, I've found it a
lot more user-friendly than other types of documentation. MSDN is
annoying to go through quickly, and man pages equally so.

Well, the only classes I've ever had to implement were the callback
interfaces and parts of the W3C DOM specification, so I can't really
say. The only class I've had to google to use, though, was ClassLoader,
although that was more a function of the fact that class-loading I've
found rather underspecified in Java.

And the provider doesn't provide a tutorial/quickstart/comprehensive
Javadoc? Besides, documentation is only as good as the developer who
wrote it.

Beware of bugs in the above code; I have only proved it correct, not
tried it. -- Donald E. Knuth

Javadoc is not for beginners

Post by Mark Spac » Tue, 20 Nov 2007 05:59:10

No, just at your (beginning) level. I can read the Javadoc just fine
now. I've already used the InetAddress Javadoc several times to look up
a constructor or method I needed. It works great.

The only complaint I have right now is that the Outputstream/Inputstream
classes should really be cross referenced with the Writer/Reader
classes. You almost always need to look at one when you have the other,
and the "see also" links from Outputstream/Inputstream don't point back
to Writer/Reader.

I don't. I press alt-F1 and my IDE takes me right to the class Javadoc
I want.

Google knows all. Google is your friend. Trust Google.

Thank you, citizen.

Javadoc is not for beginners

Post by Thomas Adr » Tue, 20 Nov 2007 06:32:46

This is my test with Non Topposting but history included

Javadoc is not for beginners

Post by Lew » Tue, 20 Nov 2007 06:42:58

Did you have an answer to the question, or other useful comment?