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

[Peter Maydell]

On Sat, 8 Feb 2020 at 07:54, Markus Armbruster <address@hidden> wrote:
> Peter Maydell <address@hidden> writes:

> > Conveniently this patchset already supports this format :-)
> > You can write either
> >
> > # @foo: bar
> > #       baz
> > #         indented
> >
> > or
> > # @foo:
> > # bar
> > # baz
> > #   indented
> >
> > and they'll come out to the same thing (the parser.py code
> > sends the same doc strings to the rST visitor).
>
> If we enforce the second format in the QAPI schema parser, we save
> ourselves the trouble of normalizing the first format to the second one.
> We also promote more uniform style.

You also end up requiring
# @foo:
# A short one-line description.

because it's the first style that makes this valid syntax:
# @foo: A short one-line description

And you're suggesting a big upheaval in doc comment style, because
lots of the existing doc comment syntax uses the first version.
I would really strongly prefer to not have "convert to supporting rST"
also mean "and we have to touch every single JSON doc comment
to convert away from a commonly used style that nobody has
complained about in the past, which doesn't compromise the ability
to include rST markup in the doc comment, and which was easy to
support in the doc generator". This patchset is already quite large
and has a lot of updates to QAPI doc comments. The one that makes
the widest set of changes (patch 9/29) is bigger than I'd like and I think
an important thing that makes it viable is that you can check with
git show that it really is just changing whitespace, not even line breaks.
Some of the style changes you're proposing would be much harder
to verify as safe and touch much more of the JSON. If you'd like
to do those I have no objection, but I really really don't want to
tangle that up with the already large amount of work involved
in transitioning away from texi to rST.

thanks
-- PMM