[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-riscv] [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function
From: |
Daniel P . Berrangé |
Subject: |
Re: [Qemu-riscv] [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header |
Date: |
Tue, 5 Feb 2019 11:04:17 +0000 |
User-agent: |
Mutt/1.10.1 (2018-07-13) |
On Tue, Feb 05, 2019 at 10:56:51AM +0000, Peter Maydell wrote:
> On Tue, 5 Feb 2019 at 06:44, Markus Armbruster <address@hidden> wrote:
> > There are two justifiable function comment placement styles: (1) next to
> > definition, and (2) next to declaration if it's in a header, else next
> > to definition.
> >
> > The rationale for the latter is having the headers do double-duty as
> > interface documentation.
> >
> > The rationale for the former is consistently placing the function
> > comments close to the code gives them a fighting chance to actually
> > match the code.
> >
> > I'm in the "next to definition" camp. If you want concise interface
> > specification, use something like Sphinx.
>
> I'm in the "next to declaration" camp. I don't want to have
> to wade into your implementation to find out what it does:
> document it for me in the interface, please.
I'm already looking at the header file to identify the function signature,
having the explanation / docs at the same place is desirable, especially
when the C file name is completely different from the header file name
forcing me to go grepping the code base to find where it is implemented.
The .c files are already volumous in size so not amenable to browsing
for the purpose of reading the docs.
Regards,
Daniel
--
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org -o- https://fstop138.berrange.com :|
|: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
[Qemu-riscv] [PATCH v3 2/3] util/cutils: Move ctype macros to "cutils.h", Philippe Mathieu-Daudé, 2019/02/04