Sergey Poznyakoff wrote: > Bruno Haible <br...@clisp.org> 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.
