Doug Mair wrote:
	> Is there anything to be learned from JavaDoc and DocLets?
	
One of the lectures in my 3rd year software engineering paper
concerns documentation.

I demonstrate JavaDoc and the frustration I experience with it
because of the large number of "navigation" tasks I _want_ to
perform (and that older tools like Masterscope and cscope let
me perform).

I then demonstrate the Squeak interface, and show how it lets me
do the things Javadoc does (including text styling and hypertext
links) *plus* most of the things I want to do that Javadoc won't
let me do.

I then remind the students that Javadoc will let me read about
classes I _haven't_ installed and may not even _have_, whereas
the Squeak navigation tools only deal with things loaded into the
image.

I then remind the students that Javadoc makes it hard to see the
documentation and the code together:  Javadoc comments are an
unbelievable clutter of junk.  Squeak makes it easy to see code
and documentation together.

I finally point out that neither approach helps you when the
document just isn't _there_ or doesn't bother to answer the
questions you have, or is wrong.

This year, I expect to follow this last step with a lecture on
JUnit/SUnit, to point out that tests are documentation which _has_
to be right, otherwise the test engine will tell you about it,
but remind students that this still doesn't help with missing
documentation or documentation that tells you a lot you don't
care about but not the thing you absolutely must know.

Oh yes, they also get to see c2man.

The bottom line is that Javadoc doesn't solve all known problems,
and for some reason tends to encourage bulky comments that don't actually
_help_ all that much.