[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Qemu-trivial] [Qemu-devel] [PATCH v3 3/3] util/cutils: Move functio

From: Markus Armbruster
Subject: Re: [Qemu-trivial] [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header
Date: Tue, 05 Feb 2019 13:30:16 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux)

Daniel P. Berrangé <address@hidden> writes:

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

If going to a definition of takes you more than a few keystrokes, your
editor is grossly deficient.

> The .c files are already volumous in size so not amenable to browsing
> for the purpose of reading the docs.
> Regards,
> Daniel

reply via email to

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