Re: [PATCH] Use Doxygen for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 2/11/14 11:19 AM, Mark Kettenis wrote:
>> Date: Tue, 11 Feb 2014 11:07:53 -0800
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>> On 2/6/14 3:55 PM, Stan Shebs wrote:
>>> Here is the official patch for the introduction of Doxygen that I
>>> proposed last fall.
>>
>> This is now pushed.
>>
>> I've added http://sourceware.org/gdb/wiki/DoxygenForGDB as the
>> initial info on what to do with it.
>>
>> I've also got defs.h, minsyms.h, and utils.[hc] in various states
>> of doxygenation, but won't spend a whole lot more time on them
>> before pushing them.
>>
>> For other popular header files, I suggest that if people
>> want to jump on any, that we use the wiki page as a simple
>> reservation system - although basic doxygenation of a file
>> need take only a few minutes, one invariably sees many ways
>> to fix up the comment blocks.
> 
> When did we agree that using doxygen was a good idea?

We did discuss it last August as part of my original proposal, then
last October with the first version of this patch.  It wasn't 100%
support, but there was enough to be worth the experiment.

> I don't want to spend my time on uglifying the source code with stuff
> that will never result in usable documentation.
> 
> I don't want to be distracted by markup when I'm reading source code
> or comments.

Basically we're talking one additional asterisk per header declaration,
which doesn't seem that onerous.  Doxygen annotation *could* get more
elaborate, but if it does, it will be because people are getting enough
value out of it to want to spend time putting the additional effort in.

> Most of all, I don't want to spend any time on arguing about these
> stupid things.

""

:-)

Stan
stan@codesourcery.com