This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Use Doxygen for internals documentation
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb-patches at sourceware dot org
- Date: Tue, 11 Feb 2014 11:52:45 -0800
- Subject: Re: [PATCH] Use Doxygen for internals documentation
- Authentication-results: sourceware.org; auth=none
- References: <52F420E0 dot 9050203 at earthlink dot net> <52FA7509 dot 4010400 at earthlink dot net> <201402111919 dot s1BJJfLP012816 at glazunov dot sibelius dot xs4all dot nl>
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