On Sat, 8 Feb 2020 at 07:54, Markus Armbruster <arm...@redhat.com> wrote: > Peter Maydell <peter.mayd...@linaro.org> 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