This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb at sourceware dot org
- Date: Fri, 09 Aug 2013 16:28:45 -0700
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <5202A6D6 dot 8090908 at earthlink dot net> <83li4ct7ot dot fsf at gnu dot org> <CADPb22ToXn8aypnpyHEFrUw_yQQiib=ieCj7WbQLSaZQM00RVg at mail dot gmail dot com> <8361vfu9t4 dot fsf at gnu dot org> <520423A2 dot 6010304 at earthlink dot net> <201308090949 dot r799nMLL024338 at glazunov dot sibelius dot xs4all dot nl>
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