From: Kevin Wolf <kwolf@redhat.com>
To: Markus Armbruster <armbru@redhat.com>
Cc: "Peter Maydell" <peter.maydell@linaro.org>,
"Daniel P. Berrangé" <berrange@redhat.com>,
qemu-devel@nongnu.org, "Michael Roth" <mdroth@linux.vnet.ibm.com>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
"Max Reitz" <mreitz@redhat.com>, "John Snow" <jsnow@redhat.com>
Subject: Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments
Date: Fri, 7 Feb 2020 11:24:33 +0100 [thread overview]
Message-ID: <20200207102433.GC6031@linux.fritz.box> (raw)
In-Reply-To: <87pnequ4og.fsf@dusky.pond.sub.org>
Am 07.02.2020 um 10:28 hat Markus Armbruster geschrieben:
> Peter Maydell <peter.maydell@linaro.org> writes:
> > @@ -4703,7 +4703,7 @@
> > #
> > # Options for creating an image format on a given node.
> > #
> > -# @driver block driver to create the image format
> > +# @driver: block driver to create the image format
> > #
> > # Since: 2.12
> > ##
>
> Loses the visual alignment. I'm okay with that, but the folks who took
> the trouble to align the text may have different ideas. Cc'ing Kevin
> and Max.
I think the documentation is much easier to parse visually with aligned
text as it makes both the option name and the whole part of the comment
that documents options stand out clearly.
Of course, "It is the QEMU coding style." would trump everything, but as
long as there isn't a style guide that requires a wall of text without
spaces and alignment, I'd prefer to leave at least those aligned texts
in place that we have.
Kevin
next prev parent reply other threads:[~2020-02-07 10:25 UTC|newest]
Thread overview: 77+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-06 17:30 [PATCH 00/29] Convert QAPI doc comments to generate rST instead of texinfo Peter Maydell
2020-02-06 17:30 ` [PATCH 01/29] configure: Allow user to specify sphinx-build binary Peter Maydell
2020-02-06 17:30 ` [PATCH 02/29] configure: Check that sphinx-build is using Python 3 Peter Maydell
2020-02-07 16:17 ` Markus Armbruster
2020-02-07 16:30 ` Peter Maydell
2020-02-08 7:50 ` Markus Armbruster
2020-02-08 13:11 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 03/29] Makefile: Fix typo in dependency list for interop manpages Peter Maydell
2020-02-06 17:30 ` [PATCH 04/29] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment Peter Maydell
2020-02-07 8:16 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 05/29] qga/qapi-schema.json: Fix indent level on doc comments Peter Maydell
2020-02-07 8:18 ` Markus Armbruster
2020-02-07 8:22 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST Peter Maydell
2020-02-07 8:32 ` Markus Armbruster
2020-02-13 16:20 ` Peter Maydell
2020-02-14 13:16 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 07/29] qapi/block-core.json: Use literal block for ascii art Peter Maydell
2020-02-07 8:50 ` Markus Armbruster
2020-02-07 9:27 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 08/29] qapi: Use ':' after @argument in doc comments Peter Maydell
2020-02-07 9:28 ` Markus Armbruster
2020-02-07 9:33 ` Max Reitz
2020-02-07 10:24 ` Kevin Wolf [this message]
2020-02-07 11:05 ` Peter Maydell
2020-02-07 14:43 ` Markus Armbruster
2020-02-07 15:01 ` Max Reitz
2020-02-07 15:40 ` Kevin Wolf
2020-02-07 15:24 ` Peter Maydell
2020-02-08 7:54 ` Markus Armbruster
2020-02-08 13:22 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 09/29] qapi: Fix indent level on doc comments in json files Peter Maydell
2020-02-07 9:31 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 10/29] qapi: Remove hardcoded tabs Peter Maydell
2020-02-07 9:32 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 11/29] qapi/ui.json: Put input-send-event body text in the right place Peter Maydell
2020-02-07 9:45 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 12/29] qapi: Explicitly put "foo: dropped in n.n" notes into Notes section Peter Maydell
2020-02-07 10:06 ` Markus Armbruster
2020-02-07 14:23 ` Eric Blake
2020-02-06 17:30 ` [PATCH 13/29] qapi/ui.json: Avoid `...' texinfo style quoting Peter Maydell
2020-02-07 10:13 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists Peter Maydell
2020-02-07 12:07 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 15/29] qapi/ui.json: " Peter Maydell
2020-02-06 17:30 ` [PATCH 16/29] qapi/{block, misc, tmp}.json: " Peter Maydell
2020-02-07 10:33 ` Philippe Mathieu-Daudé
2020-02-06 17:30 ` [PATCH 17/29] qapi: Add blank lines before " Peter Maydell
2020-02-07 10:11 ` Philippe Mathieu-Daudé
2020-02-06 17:30 ` [PATCH 18/29] qapi/migration.json: Replace _this_ with *this* Peter Maydell
2020-02-07 16:54 ` Markus Armbruster
2020-02-07 17:00 ` Peter Maydell
2020-02-08 14:24 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Peter Maydell
2020-02-07 15:34 ` Markus Armbruster
2020-02-07 16:13 ` Peter Maydell
2020-02-08 14:10 ` Markus Armbruster
2020-02-08 14:43 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 20/29] qapi/machine.json: Escape a literal '*' in doc comment Peter Maydell
2020-02-06 17:30 ` [PATCH 21/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py Peter Maydell
2020-02-06 17:30 ` [PATCH 22/29] scripts/qapi/parser.py: improve doc comment indent handling Peter Maydell
2020-02-06 17:30 ` [PATCH 23/29] docs/sphinx: Add new qapi-doc Sphinx extension Peter Maydell
2020-02-06 17:30 ` [PATCH 24/29] docs/interop: Convert qemu-ga-ref to rST Peter Maydell
2020-02-06 17:30 ` [PATCH 25/29] docs/interop: Convert qemu-qmp-ref " Peter Maydell
2020-02-06 17:30 ` [PATCH 26/29] qapi: Use rST markup for literal blocks Peter Maydell
2020-02-06 17:30 ` [PATCH 27/29] qga/qapi-schema.json: Add some headings Peter Maydell
2020-02-06 17:30 ` [PATCH 28/29] scripts/qapi: Remove texinfo generation support Peter Maydell
2020-02-06 17:59 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 29/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Peter Maydell
2020-02-06 18:47 ` [PATCH 00/29] Convert QAPI doc comments to generate rST instead of texinfo Peter Maydell
2020-02-06 19:53 ` no-reply
2020-02-06 19:56 ` no-reply
2020-02-07 17:00 ` Markus Armbruster
2020-02-07 17:10 ` Peter Maydell
2020-02-08 14:15 ` Markus Armbruster
2020-02-08 14:59 ` Peter Maydell
2020-02-10 0:34 ` Aleksandar Markovic
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=20200207102433.GC6031@linux.fritz.box \
--to=kwolf@redhat.com \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=jsnow@redhat.com \
--cc=mdroth@linux.vnet.ibm.com \
--cc=mreitz@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).