Subject: Re: Adding to KNF.
To: Martin Husemann <firstname.lastname@example.org>
From: Lord Isildur <email@example.com>
Date: 06/16/2002 19:19:49
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!)
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)