From: Markus Armbruster <armbru@redhat.com>
To: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
qemu-riscv@nongnu.org, "QEMU Trivial" <qemu-trivial@nongnu.org>,
"QEMU Developers" <qemu-devel@nongnu.org>,
"Stefano Garzarella" <sgarzare@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>,
"David Gibson" <david@gibson.dropbear.id.au>
Subject: Re: [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header
Date: Tue, 05 Feb 2019 13:30:16 +0100 [thread overview]
Message-ID: <87bm3qto2v.fsf@dusky.pond.sub.org> (raw)
In-Reply-To: <20190205110417.GF20321@redhat.com> ("Daniel P. =?utf-8?Q?Ber?= =?utf-8?Q?rang=C3=A9=22's?= message of "Tue, 5 Feb 2019 11:04:17 +0000")
Daniel P. Berrangé <berrange@redhat.com> writes:
> On Tue, Feb 05, 2019 at 10:56:51AM +0000, Peter Maydell wrote:
>> On Tue, 5 Feb 2019 at 06:44, Markus Armbruster <armbru@redhat.com> 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
WARNING: multiple messages have this Message-ID (diff)
From: Markus Armbruster <armbru@redhat.com>
To: "Daniel P. Berrangé" <berrange@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
qemu-riscv@nongnu.org, "QEMU Trivial" <qemu-trivial@nongnu.org>,
"QEMU Developers" <qemu-devel@nongnu.org>,
"Stefano Garzarella" <sgarzare@redhat.com>,
"Philippe Mathieu-Daudé" <philmd@redhat.com>,
"David Gibson" <david@gibson.dropbear.id.au>
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 [thread overview]
Message-ID: <87bm3qto2v.fsf@dusky.pond.sub.org> (raw)
In-Reply-To: <20190205110417.GF20321@redhat.com> ("Daniel P. =?utf-8?Q?Ber?= =?utf-8?Q?rang=C3=A9=22's?= message of "Tue, 5 Feb 2019 11:04:17 +0000")
Daniel P. Berrangé <berrange@redhat.com> writes:
> On Tue, Feb 05, 2019 at 10:56:51AM +0000, Peter Maydell wrote:
>> On Tue, 5 Feb 2019 at 06:44, Markus Armbruster <armbru@redhat.com> 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
next prev parent reply other threads:[~2019-02-05 12:30 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-02-04 21:12 [Qemu-devel] [PATCH v3 0/3] cutils: Cleanup, improve documentation Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-riscv] " Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-devel] [PATCH v3 1/3] util/cutils: Move size_to_str() from "qemu-common.h" to "cutils.h" Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-riscv] " Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-devel] [PATCH v3 2/3] util/cutils: Move ctype macros " Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-riscv] " Philippe Mathieu-Daudé
2019-02-05 10:32 ` [Qemu-devel] " Cornelia Huck
2019-02-05 10:32 ` [Qemu-riscv] " Cornelia Huck
2019-02-05 10:49 ` [Qemu-devel] " Daniel P. Berrangé
2019-02-05 10:49 ` [Qemu-riscv] " Daniel P. Berrangé
2019-02-04 21:12 ` [Qemu-devel] [PATCH v3 3/3] util/cutils: Move function documentations to the header Philippe Mathieu-Daudé
2019-02-04 21:12 ` [Qemu-riscv] " Philippe Mathieu-Daudé
2019-02-05 6:42 ` [Qemu-devel] " Markus Armbruster
2019-02-05 6:42 ` [Qemu-riscv] " Markus Armbruster
2019-02-05 10:56 ` Peter Maydell
2019-02-05 10:56 ` [Qemu-riscv] " Peter Maydell
2019-02-05 11:04 ` Daniel P. Berrangé
2019-02-05 11:04 ` [Qemu-riscv] " Daniel P. Berrangé
2019-02-05 12:30 ` Markus Armbruster [this message]
2019-02-05 12:30 ` Markus Armbruster
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87bm3qto2v.fsf@dusky.pond.sub.org \
--to=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=david@gibson.dropbear.id.au \
--cc=peter.maydell@linaro.org \
--cc=philmd@redhat.com \
--cc=qemu-devel@nongnu.org \
--cc=qemu-riscv@nongnu.org \
--cc=qemu-trivial@nongnu.org \
--cc=sgarzare@redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.