[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentation
From: |
Peter Maydell |
Subject: |
Re: [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header |
Date: |
Tue, 5 Feb 2019 10:56:51 +0000 |
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.
My standard for patches I review is "if this is adding a new
function prototype in a header file, add a doc comment".
thanks
-- PMM