[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
Re: [Qemu-riscv] [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header
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".
[Qemu-riscv] [PATCH v3 2/3] util/cutils: Move ctype macros to "cutils.h", Philippe Mathieu-Daudé, 2019/02/04