i'll second this.. typically ive found that the automatically generated 
stuff is not very useful, and when it is actually useful it is somethign 
that i would (or do, out of habit) write a one-liner awk script to 
generate at the moment i need it.. and of those cases where such a thing 
does end up being useful, i'd say 60% of them are of the form 'who else 
references this?' and 40% are of the form 'where is this function called?'.. 
i dont do java so i never got any warm feeling from javadoc, but i fancy 
it wont be a very different case there. my biggest gripe about 
'automatic' documentation is that it tends to be used, at least in 
some cases ive had the misfortune to deal with, as a substitute for real 
documentation, and it just can't hold a candle to a simple, concise, well 
thought out explanation of the use of a thing, written by someone 
(probably the author) who knew how all the pieces fit together when it was 
written. comlicated things, or general big-picture things belong in a man 
page or a supplementary document, anyway. (and ultimately in a book! e.g. 
the 4.3 daemon book and the red 4.4 daemon book. if someone wrote a 
'modern-netbsd' daemon book i'd buy it!) 
my .02
isildur

On Sun, 16 Jun 2002, Martin Husemann wrote:

> > If we're going to do something like this, then I suggest people take
> > a look at doxygen (which can generate manual-type documentation from
> > marked up comments in source files).
> 
> Well, my $0.02:
> 
> I don't know doxygen at all, but I've worked with various similar things
> during my professional life. I have never seen this approach succeed.
> 
> I'm a big fan of
> 
>  - free form comment blocks preceding functions that need it
>  - good (but mostly short) comments in header files
>  - extensive use of asserts and similar run-time checks
>  - extensive (internal) documentation similar to our section 9 man pages
>  - special case docs in HTML format at some well known place (sometimes
>    you just need graphics to explain something)
> 
> But that's just me, and what we ended up doing at my company (after trying yet
> another tools when we started from scratch last year)
> 
> Martin
>