Re: A new strategy for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 8/9/13 2:49 AM, Mark Kettenis wrote:
>> Date: Thu, 08 Aug 2013 16:02:58 -0700
>> From: Stan Shebs <stanshebs@earthlink.net>
>>

>> 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.

It does look that way :-) , but I'm not under any illusion that it will
somehow magically change what people do.  It does address a couple of
the extant complaints, by expanding on the source-code commenting that
is a well-established habit now, and by having good support for API
specification.

On the general subject of technical solutions changing social behavior,
I will risk embarrassing myself by noting that I was long against moving
GDB to a public repository, because I didn't think it was going to
result in any more patches being contributed - after all, it was the
same sources and the same approval process, so what difference did it
make?  I think I've been decisively proven wrong about that one! :-)

Stan
stan@codesourcery.com