Re: New module argp-version-etc

[Jim Meyering]

Sergey Poznyakoff wrote:
> Bruno Haible <address@hidden> ha escrit:
...
>>   +/* Like version_etc, below, but with the NULL-terminated author list
>>   +   provided via a variable of type va_list.  */
>>
>>   Ouch! Not only you expect the user to look up the documentation of the
>>   API inside a long source file, but you also play paper chase with the
>>   user.
>
> Not me :^) It was the original comment in version_etc.c. I did not touch it.

Bruno has expressed his preference to put per-function documentation in
the .h file alongside the prototype.  He has explained that he does this
in an attempt to make it easier to find for *users* of the function.
Perhaps that makes sense with a real library, but with gnulib, the
sources are alongside the .h files far more often than they would be
for a "normal" library.

I find that putting the function specification closer to the source
is better for me, as developer/debugger/maintainer, and even as user.
When the spec and code are in the same file, I find that I am more likely
to read the spec while reading the code, and also to adjust the spec if
I change the code -- I need any help I can get, on this front ;-).
That's why in version_etc.c, and in any other module I write, I put the
function-describing comment immediately before the function body.

Another issue: consistency.  With Bruno's approach, a public function must
have *no* spec just before its definition, while each private one does.
I think we all agree that duplicating the spec (before definition and in
the .h file) is not maintainable.

It's not a big deal for me, now that I'm used to seeing no documentation
in gnulib's .c files for certain public functions, but it still does rankle
a little, each time I notice.