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

[Cornelia Huck <cohuck@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 1091 bytes --]

On Fri, 4 Jan 2019 14:17:14 -0600
Eric Blake <eblake@redhat.com> wrote:

> 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); 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.
> 

Another vote for documentation in .c files: If I use tags, I jump to
the implementation, not the declaration.

But also +1 for consistency.

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]