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