Re: [Qemu-trivial] [Qemu-devel] [PATCH v2 3/3] util/cutils: Move function documentations to the header

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> On 1/4/19 12:12 PM, Philippe Mathieu-Daudé wrote:
>> Many functions have documentation before the implementation in
>> cutils.c. Since we expect documentation around the prototype
>> declaration in headers, move the comments in cutils.h.
>> 
>> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
>> ---
>>  include/qemu/cutils.h | 224 ++++++++++++++++++++++++++++++++++++++++++
>>  util/cutils.c         | 185 ----------------------------------
>>  2 files changed, 224 insertions(+), 185 deletions(-)
>
> I find documentation in .c files slightly easier to use (you can then
> read the code right below to see if the documentation is still
> accurate);

This is the kicker for me.  I try to cultivate a healthy suspicion of
comments in general, x10 for comments acting at a distance.

>            but as we had an inconsistent mix, I'm also okay with your
> patch consolidating all the documentation to one of the two files,
> rather than the bad mix of half-and-half.

Concur.