This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [PATCH] Doxygenate defs.h
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb-patches at sourceware dot org
- Date: Tue, 18 Feb 2014 11:52:03 -0800
- Subject: Re: [PATCH] Doxygenate defs.h
- Authentication-results: sourceware.org; auth=none
- References: <530285BC dot 90102 at earthlink dot net> <201402172217 dot s1HMHOAT001833 at glazunov dot sibelius dot xs4all dot nl>
On 2/17/14 2:17 PM, Mark Kettenis wrote:
>> Date: Mon, 17 Feb 2014 13:57:16 -0800
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>> This is a first patch that modifies source code to be more useful with
>> Doxygen. It does little more than add an extra "*" to comment blocks
>> that document the source construct immediately following.
>>
>> In keeping with our usual practice, I have not changed anything outside
>> comments, and the comments themselves are only minimally tweaked,
>> despite the great temptation to expand on some of the more cryptic. :-)
>>
>> I'll push this in a couple days if people are willing to live with this
>> format for comments. Next up, minsyms.h.
>
> Sorry, no, I'm not willing to live with this. It's making the
> comments significantly harder to read.
Really? We have a half-million lines of C, the language whose syntax is
one step above line noise, and it's an extra asterisk in comment blocks
that makes it significantly harder to read? :-)
> And what benefit does the
> documentation have over just reading the header file?
Cross-links and formatting, to start with. For instance, clicking on
the name of a struct in a function signature takes you to its
definition. If reading the header file suffices for you, that's great,
but I personally spend a lot of time grepping around and then trying to
make sense of the spew.
> There really is
> only one thing that the old internals documentation tried to provide
> that the comments in the source code aren't very good at: explaining
> how the interfaces work together. And that's not something Doxygen is
> going to provide.
Doxygen actually has sufficient machinery to build a version of the
internals manual from comment blocks in the code; I didn't lead with
that because the individual construct documentation is useful to
people, and a simpler starting place. But I can start with that if you
like.
> BTW, you realize this all violates the GNU coding standards.
Really? I'd be interested in the specific passages that you think
are being violated. I note that the the standards have very few
hard rules that individual projects cannot decide to supersede,
mostly having to do with the copyleft.
I also note that libstdc++, GNU radio, and other GNU projects have been
using Doxygen for some time, so it's not like GDB is even the first.
Stan
stan@codesourcery.com