[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments
From: |
Peter Maydell |
Subject: |
Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments |
Date: |
Fri, 7 Feb 2020 11:05:42 +0000 |
On Fri, 7 Feb 2020 at 10:24, Kevin Wolf <address@hidden> wrote:
>
> Am 07.02.2020 um 10:28 hat Markus Armbruster geschrieben:
> > Peter Maydell <address@hidden> 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.
So, the other way to handle this would be to say "the @foo: can have
an arbitrary amount of whitespace after it", and have the doc comment
parser strip out that many characters of extra whitespace there and
on the subsequent lines. The downside is that then you would have no
way of having a comment for an argument which started with rST markup
that required leading whitespace. I think this pretty much would just
mean that you can't start an argument description with a blockquote,
so we don't lose much, but there is a difference currently between:
@arg: In the current parser this is a blockquote
Blockquote line 2
But this is a non-blockquoted line still in @arg's description
and
@arg: This is not blockquoted, it's just a line
So is this
and this
I can make the parser work the other way if people prefer that though
(and then the first example above would become a syntax error because
the 3rd line would be unexpectedly de-indented).
thanks
-- PMM
- Re: [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST, (continued)
[PATCH 07/29] qapi/block-core.json: Use literal block for ascii art, Peter Maydell, 2020/02/06
[PATCH 08/29] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/06
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Markus Armbruster, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Max Reitz, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Kevin Wolf, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments,
Peter Maydell <=
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Markus Armbruster, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Max Reitz, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Kevin Wolf, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Markus Armbruster, 2020/02/08
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/08
[PATCH 11/29] qapi/ui.json: Put input-send-event body text in the right place, Peter Maydell, 2020/02/06
[PATCH 13/29] qapi/ui.json: Avoid `...' texinfo style quoting, Peter Maydell, 2020/02/06