Java Help - Javadoc is not for beginners

Author

Javadoc is not for beginners

Thomas Adrian

2007-11-17, 8:12 am

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

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.

Thanks
Thomas
http://www.notessidan.se

Andrew Thompson

2007-11-17, 8:12 am

Thomas Adrian wrote:
...
>Take for instance this class:
>http://java.sun.com/j2se/1.4.2/docs...netAddress.html
..
>...so I right away know how to implement the class I am
>currently looking at in javadoc.

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
<http://java.sun.com/j2se/1.4.2/docs...s.html#java.net
>

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
interesting..
<http://java.sun.com/j2se/1.4.2/docs...#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)
getLocalHost()

HTH

--
Andrew Thompson
http://www.athompson.info/andrew/

Message posted via http://www.javakb.com

Eric Sosman

2007-11-17, 7:14 pm

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

Hunter Gratzner

2007-11-17, 7:14 pm

On Nov 17, 12:33 pm, Thomas Adrian <notessi...@gmail.com> wrote:
> One thing that bothers me is the Javadoc part.

That does not excuse you from reading it.

Mark Space

2007-11-17, 10:20 pm

Thomas Adrian wrote:

> As a beginner this page is not very informative.

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":

http://java.sun.com/docs/books/tuto...oadcasting.html

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.

Thomas Adrian

2007-11-18, 4:40 am

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

- Thomas

On Nov 18, 3:57 am, Mark Space <marksp...@sbc.global.net> wrote:
> Thomas Adrian wrote:
>
> 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":
>
> http://java.sun.com/docs/books/tuto...ams/broadcas...
>
> 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.

Roedy Green

2007-11-18, 4:40 am

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

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

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
http://mindprod.com

Roedy Green

2007-11-18, 4:40 am

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

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

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
http://mindprod.com

Patricia Shanahan

2007-11-18, 7:17 pm

Roedy Green wrote:
> On Sat, 17 Nov 2007 03:33:40 -0800 (PST), Thomas Adrian
> <notessidan@gmail.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.

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.

Patricia

Lew

2007-11-18, 7:17 pm

Thomas Adrian wrote:
> Thank you all for replying,

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

> - If javadoc is just a reference, it should be renamed to javaref

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

> - My point here is that it is very difficult to understand how to
> implement certain classes by just lookung at the javadoc.

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

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

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

> - Really, how many of you do not google the class you are about to
> implement ?

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

> - A lot of classes out there is not made by Sun , so they may not be
> googable.

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

--
Lew

Joshua Cranmer

2007-11-18, 7:17 pm

Thomas Adrian wrote:
> Thank you all for replying,
>
> - If javadoc is just a reference, it should be renamed to javaref

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.

> - My point here is that it is very difficult to understand how to
> implement certain classes by just lookung at the javadoc.

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.

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

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.

> - Really, how many of you do not google the class you are about to
> implement ?

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.

> - A lot of classes out there is not made by Sun , so they may not be
> googable.

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

Mark Space

2007-11-18, 7:17 pm

Thomas Adrian wrote:

> - My point here is that it is very difficult to understand how to
> implement certain classes by just lookung at the javadoc.

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.

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

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.

> - Really, how many of you do not google the class you are about to
> implement ?

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

> - A lot of classes out there is not made by Sun , so they may not be
> googable.

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

Thank you, citizen.

Thomas Adrian

2007-11-18, 7:17 pm

On 18 Nov, 17:27, Lew <l...@lewscanon.com> wrote:
> Thomas Adrian wrote:
>
> 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?
>
> --
> Lew

This is my test with Non Topposting but history included

Lew

2007-11-18, 7:17 pm

Lew wrote:

Thomas Adrian wrote:[color=darkred]
> This is my test with Non Topposting but history included

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

--
Lew

Thomas Adrian

2007-11-19, 8:14 am

On Nov 18, 10:42 pm, Lew <l...@lewscanon.com> wrote:
> Lew wrote:
> Thomas Adrian wrote:
>
> Did you have an answer to the question, or other useful comment?
>
> --
> Lew

Well, I am not "yet" writing javadocs, But I am working with Lotus
Notes and there is a new version out that is based on Eclipse.
This means a new world opens for java developers who want to hook into
Lotus Notes, but the documentation for implementing the new classes
provided by the Notes client are not very well documented.

- T

Roedy Green

2007-11-19, 8:14 am

On Sun, 18 Nov 2007 07:31:47 -0800, Patricia Shanahan <pats@acm.org>
wrote, quoted or indirectly quoted someone who said :

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

I wish this advice were more commonly taught.
--
Roedy Green Canadian Mind Products
The Java Glossary
http://mindprod.com

Eric Sosman

2007-11-19, 7:20 pm

Thomas Adrian wrote:
> On Nov 18, 10:42 pm, Lew <l...@lewscanon.com> wrote:
>
> Well, I am not "yet" writing javadocs, But I am working with Lotus
> Notes and there is a new version out that is based on Eclipse.
> This means a new world opens for java developers who want to hook into
> Lotus Notes, but the documentation for implementing the new classes
> provided by the Notes client are not very well documented.

IMHO, if you are writing Java code and not writing the
Javadoc comments that accompany it, you are doing yourself
a disservice. When you lay the code aside for three months
and then pick it up again to make some kind of improvement,
the lack of documentation will cost you more time than you
would have spent writing the comments.

For me (I can't speak for others), the process of writing
Javadoc also helps clarify my thinking. If I'm having trouble
writing a concise statement of what some method does or what
some variable or parameter means, that's a clue that I haven't
quite thought through the consequences of my design and should
take another look at it. This has proved such a helpful sanity
check that I've taken to writing Javadoc even for `private'
members (although I usually don't bother <code> tags and such).

Write Javadoc. It's good for the soul.

--
Eric Sosman
esosman@ieee-dot-org.invalid

Are Nybakk

2007-11-20, 7:19 pm

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...netAddress.html
>
> As a beginner this page is not very informative.
>

If you ask me, javadocs is one of the very best things about java. It is
so simple when you have such a well documented, easy-to-understand
documentation. It takes a little while to get familiar with, but you
will appreciate quickly. Also, since you can generate javadoc for your
own projects, others that might try to understand your design will
easily (well this still demand some wellformatted descriptions from the
developer) be able to check the documentation since it follows a
standard form.

I've been programming a little in C++ and I absolutely hate the
documentation part. I want something more like javadoc D: In my last
assignment I even added Javadoc style comments in my header files
because it was more descriptive to me :p

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

If a class has constructors, there's a header for it before methods.
Look at http://java.sun.com/j2se/1.4.2/docs...ang/Object.html
for instance. It could have been clarified I guess, but since there is
no constructor mentioned, there is none.

> And why is there never any examplecode in the javadoc
>

There is in some docs, but you can find examples in the tutorials.
Javadoc is a dictionary, not a book for learning java =)

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

My tip is to just give it a try. I got used to it after looking at it
for some time - browsing around for simple classes and exploring.

>
> Thanks
> Thomas
> http://www.notessidan.se
>

Are Nybakk

2007-11-20, 7:19 pm

Ed Kirwan

2007-11-20, 7:19 pm

Eric Sosman wrote:

>
> For me (I can't speak for others), the process of writing
> Javadoc also helps clarify my thinking. If I'm having trouble
> writing a concise statement of what some method does or what
> some variable or parameter means, that's a clue that I haven't
> quite thought through the consequences of my design and should
> take another look at it. This has proved such a helpful sanity
> check that I've taken to writing Javadoc even for `private'
> members (although I usually don't bother <code> tags and such).
>
> Write Javadoc. It's good for the soul.
>

Amen.

Though you can almost hear the distant, thundering hooves of the horses
pulling the bandwagon into town, and the, "Yeeeeee-haws!" of the
X-Driven-Design boys as they fire their JavaDoc-Driven-Design six-shooters
into the air.

"JDD," even has a nice ring to it.

--
..ed

www.EdmundKirwan.com - Home of encapsulation theory.

Lew

2007-11-20, 7:19 pm

Are Nybakk wrote:
> If you ask me, javadocs is one of the very best things about java. It is
> so simple when you have such a well documented, easy-to-understand
> documentation. It takes a little while to get familiar with, but you
> will appreciate quickly. Also, since you can generate javadoc for your
> own projects, others that might try to understand your design will
> easily (well this still demand some wellformatted descriptions from the
> developer) be able to check the documentation since it follows a
> standard form.
>
> I've been programming a little in C++ and I absolutely hate the
> documentation part. I want something more like javadoc D: In my last
> assignment I even added Javadoc style comments in my header files
> because it was more descriptive to me :p
>

Check out Doxygen.
<http://en.wikipedia.org/wiki/Doxygen>
and links from there.
<http://www.stack.nl/~dimitri/doxygen/>

--
Lew

Are Nybakk

2007-11-21, 7:17 pm

Lew wrote:
> Are Nybakk wrote:
>
> Check out Doxygen.
> <http://en.wikipedia.org/wiki/Doxygen>
> and links from there.
> <http://www.stack.nl/~dimitri/doxygen/>
>

Aah, thanks a thousand.

Thomas Adrian

2007-11-22, 8:12 am

On Nov 20, 10:04 pm, Are Nybakk <n...@arenybakk.com> wrote:[color=darkred]
> Thomas Adrian wrote:
>
>
>
>
>
> If you ask me, javadocs is one of the very best things about java. It is
> so simple when you have such a well documented, easy-to-understand
> documentation. It takes a little while to get familiar with, but you
> will appreciate quickly. Also, since you can generate javadoc for your
> own projects, others that might try to understand your design will
> easily (well this still demand some wellformatted descriptions from the
> developer) be able to check the documentation since it follows a
> standard form.
>
> I've been programming a little in C++ and I absolutely hate the
> documentation part. I want something more like javadoc D: In my last
> assignment I even added Javadoc style comments in my header files
> because it was more descriptive to me :p
>
>
> If a class has constructors, there's a header for it before methods.
> Look athttp://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html
> for instance. It could have been clarified I guess, but since there is
> no constructor mentioned, there is none.
>
>
> There is in some docs, but you can find examples in the tutorials.
> Javadoc is a dictionary, not a book for learning java =)
>
>
>
>
> My tip is to just give it a try. I got used to it after looking at it
> for some time - browsing around for simple classes and exploring.
>
>
>

Thank you all for replying.
I am still looking for someone who can explain to me how to read a
javadoc so I know how to implement a class.
Please, give me some walk through how you guys think when looking at a
javadoc, what is the first thing you look at, and what's the next
step.

Thanks
Thomas

Patricia Shanahan

2007-11-22, 10:15 pm

Thomas Adrian wrote:
....
> Thank you all for replying.
> I am still looking for someone who can explain to me how to read a
> javadoc so I know how to implement a class.
> Please, give me some walk through how you guys think when looking at a
> javadoc, what is the first thing you look at, and what's the next
> step.
....

How I read a Javadoc depends on what I am doing, and what I am trying to
find out.

If I am not familiar with the package, I would begin by reading the
package documentation.

Similarly, if I am not familiar with the class I read the beginning of
the page for the class.

You talk about "implement a class". That is, for me, a much rarer
situation than needing to use the class. For most uses, I do a quick
scan of the summary tables to find the constructors and methods I need,
then read the details for those methods. I assume from the existence of
the summary tables that the designers of Javadoc expected that behavior.

If I needed to implement an interface or extend a class I would usually
begin by creating a Junit test and an empty class declaration in Eclipse
with the right superclass or interface. That will get me an Eclipse
error marker that I resolve by telling it to add the necessary method
declarations.

After that, I go through the method declarations reading the Javadoc
comment for each, deciding what it means in my new class, writing the
unit test according to that documentation and then writing the code. In
some cases I will need to override a non-abstract method. Again, I do it
by using Eclipse to produce the proper declaration and the Javadoc for
the method to tell me the rules for it.

I hope this is something like what you want.

Patricia

Thomas Adrian

2007-11-22, 10:15 pm

On Nov 22, 4:02 pm, Patricia Shanahan <p...@acm.org> wrote:
> Thomas Adrian wrote:
>
> ...> Thank you all for replying.
>
> ...
>
> How I read a Javadoc depends on what I am doing, and what I am trying to
> find out.
>
> If I am not familiar with the package, I would begin by reading the
> package documentation.
>
> Similarly, if I am not familiar with the class I read the beginning of
> the page for the class.
>
> You talk about "implement a class". That is, for me, a much rarer
> situation than needing to use the class. For most uses, I do a quick
> scan of the summary tables to find the constructors and methods I need,
> then read the details for those methods. I assume from the existence of
> the summary tables that the designers of Javadoc expected that behavior.
>
> If I needed to implement an interface or extend a class I would usually
> begin by creating a Junit test and an empty class declaration in Eclipse
> with the right superclass or interface. That will get me an Eclipse
> error marker that I resolve by telling it to add the necessary method
> declarations.
>
> After that, I go through the method declarations reading the Javadoc
> comment for each, deciding what it means in my new class, writing the
> unit test according to that documentation and then writing the code. In
> some cases I will need to override a non-abstract method. Again, I do it
> by using Eclipse to produce the proper declaration and the Javadoc for
> the method to tell me the rules for it.
>
> I hope this is something like what you want.
>
> Patricia

Thanks Patricia
That sound like a good start for me.

- Thomas

Sponsored Links