Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments

[Peter Maydell <peter.maydell@linaro.org>]

On Fri, 7 Feb 2020 at 10:24, Kevin Wolf <kwolf@redhat.com> wrote:
>
> 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.

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