[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-trivial] [Qemu-devel] [PATCH v2 3/3] util/cutils: Move functio

From: Markus Armbruster
Subject: Re: [Qemu-trivial] [Qemu-devel] [PATCH v2 3/3] util/cutils: Move function documentations to the header
Date: Mon, 07 Jan 2019 14:40:01 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux)

Eric Blake <address@hidden> 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é <address@hidden>
>> ---
>>  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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]