This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [RFC] Stop putting function comments in foo.h


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]