This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [RFC] Stop putting function comments in foo.h
- From: Stan Shebs <stanshebs at earthlink dot net>
- To: gdb-patches at sourceware dot org
- Date: Mon, 17 Mar 2014 14:56:12 -0700
- Subject: Re: [RFC] Stop putting function comments in foo.h
- Authentication-results: sourceware.org; auth=none
- References: <CADPb22QBBrYB70YoL-Aqyfi77gphGija4zK5mSgYckwfZ7e84g at mail dot gmail dot com> <53271DC0 dot 3050405 at redhat dot com>
On 3/17/14 9:07 AM, Pedro Alves wrote:
> On 03/15/2014 07:45 PM, Doug Evans wrote:
>> I'd like to start a discussion.
>> With doxygen is there still as much value to putting function comments
>> in foo.h instead of foo.c?
>
> IMO, yes. And IMO doxygen here is a red herring.
> I actually don't see myself looking at doxygen docs
> much. Doxygen is supposed to be an aid, there should be no
> requirement to build the doxygen docs to be able to understand
> gdb's sources, right?
I think that's the right viewpoint. Doxygen normally glues .h and
.c comment blocks into a single documentation node, which nicely
finesses the whole question of where to record API info, but even
so it seems a bit sloppy for us to not make a decision on .h vs .c.
> IMO, a module's API documentation should be in its header file, as
> that's where the module's "public" contract is defined.
> Needing to peek at the module's implementation feels wrong to me.
> If the function's documentation isn't clear without looking
> at the function's body, something is already wrong with
> the comment.
I've flip-flopped on this so many times...
While it seems most logical to have the API documentation in the .h
file, in actual practice the "see foo.h" comments seem awkward and
unhelpful. It's matched only by the possibility of having no comment
block at all, since many functions in our API have uninteresting bodies.
Going the other way has its own issues, for instance only function and
variable documentation gets to be in a .c file, structs and enums and
macros have to stay in the .h anyway.
At the moment I'm leaning to API in .h, and put down the "see" comments
as one of the many minor irritations in the C programmer's life. :-)
>> I ask because every time I find a "See foo.h." comment I get depressed
>> and disappointed. They're just getting in my way, and I'm wondering
>> if it's just me.
>
> Whenever I look at a header file that doesn't document its
> functions' interfaces (and often doesn't even list the
> parameter names), I get depressed and disappointed. I'm
> wondering if it's just me. :-)
One of the potential uses for Doxygen is that it has ways to dump
raw info about the sources, and we could use that to build things
like progress meters - identify the 10 most-used functions that are
undocumented and write comments for those, then do the next 10, etc.
Right now it's just the large amorphous need, where fixing it feels
like trying to empty the ocean with a teaspoon. :-)
Stan
stan@codesourcery.com