Re: [PATCH] Doxygenate defs.h

[Stan Shebs <stanshebs@earthlink.net>]

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