[Top][All Lists]

[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: Peter Maydell
Subject: Re: [Qemu-riscv] [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".

-- PMM

reply via email to

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