Re: A new strategy for internals documentation

[Mark Kettenis <mark.kettenis@xs4all.nl>]

> Date: Thu, 08 Aug 2013 16:02:58 -0700
> From: Stan Shebs <stanshebs@earthlink.net>
> 
> 3. Introduce an annotation/structured scheme in source code comments.
> 
> You're skeptical, but not opposed to this, right?

It's not going to make the source code comments more readable.  Will
probably make people focus on getting the sybtax of the annotations
right instead of the actual context.

> 4. Use Doxygen.
> 
> Are you for or against, or indifferent?
> 
> (For me Doxygen gets the nod by elimination, if nothing else.  In the
> rather lengthy
> 
> http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
> 
> there are not a lot of options that are portable, GPL, etc.  LLVM's use
> of Doxygen, http://llvm.org/doxygen/index.html , seems pretty useful.)

Yeah, that's a typical example of doxygen-generated documentation.
Lots of function prototypes, a few inheritance diagrams, and barely
any actual content.  Not my defenition of useful.  In fact I'm pretty
much conditioned such that my response to seeing doxygen generated
pages is to not ever bother reading it.

Stan, I fear you're proposing a technical solution for a social
probleem.