On Sat, May 21, 2005 at 01:48:12PM -0400, Thor Lancelot Simon wrote:
> On Sat, May 21, 2005 at 09:11:05AM +0000, Rui Paulo wrote:
> > On 2005-05-21, Jan Schaumann <jschauma@netmeister.org> wrote:
> > > Hey, this is pretty cool!  I don't know doxygen, but this looks like
> > > something we may want to get onto our website, no?
> > 
> > I agree. I could handle it, if there's no one against it :) 
> 
> I am strongly opposed to adding *even more* documentation formats to our
> system.  I have also had some prior experience with doxygen and loathe it.

FWIW, I tend to agree with Thor Lancelot Simon. The examples I have seen
with doxygen just emphasize that this seems to be a poor hack to
advertise documentation that is indeed missing, and tends just to bloat
sources.

Good software documentation is hard. It's a combination of good readable
code, and well written and thought documentation (in no way automatic).
This can be done separately (BSD is outstanding in this area, with 
readable good code (specially NetBSD) and outstanding quality man pages
and papers---not to mention the red daemon book: not every system out
there has such a documentation, and I have sometimes the feeling that,
lacking clear engineering, this is perhaps because it would be quite
challenging to describe some systems as a whole...). 

Or go Donald Knuth's CWEB, "weaving" the two (and you will 
see how hard it is to put things right---been there, seen that; the use
of the system is not hard at all, it's quite easy; the _task_ is
challenging).

Everything easy is not "in the middle". It's simply out of purpose and
tends to hide the problems.

My two cents,
-- 
Thierry Laronde (Alceste) <tlaronde +AT+ polynum +dot+ com>
http://www.kergis.org/  |  http://www.kergis.com/
Key fingerprint = 0FF7 E906 FBAF FE95 FD89  250D 52B1 AE95 6006 F40C