Re: [PATCH v5 08/20] scripts/qapi/parser.py: improve doc comment indent handling

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

On Tue, 22 Sep 2020 at 08:27, Markus Armbruster <armbru@redhat.com> wrote:
> How does
>
>   @foo:  bar
>          baz
>   @frob: gnu
>          gnat
>
> behave?

The rST fragments would be:

 bar
 baz

gnu
gnat

So you get what rST does with that. We do actually have examples
of this in the existing QAPI doc comments. It ends up treating it
as a definition list where the term is 'bar' and the
definition is 'baz' (which I don't entirely understand, I was
expecting a block-quote). That renders sufficiently close to correct
that I hadn't noticed it.

It would be a fairly small change to determine the indent level by
looking for the first non-ws character on line 1 after the colon.
Since we have a fair amount of this style in the code and it's
as you say a natural-seeming thing to write that seems the best
thing. (If you really wanted to start the option documentation with
some rST that required an initial indent, probably because you're
writing a literal-text Examples section, then you'd need to use the
"nothing after the : on line 1, rST fragment begins on line 2 in
column 0" style. Which would be the most natural way to write
that literal text anyway.)

I guess at this point I'll potentially create work for myself
by drawing your attention to the rST syntax for field lists
and option lists:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists
which are kind of similar to what we're doing with @foo: stuff
markup, and which handle indentation like this:

:Hello: This field has a short field name, so aligning the field
        body with the first line is feasible.

:Number-of-African-swallows-required-to-carry-a-coconut: It would
    be very difficult to align the field body with the left edge
    of the first line. It may even be preferable not to begin the
    body on the same line as the marker.

The differences to what I have implemented in this series are:
 * indent of lines 2+ is determined by the indent of line 2, not 1
 * lines 2+ must be indented, so anything that currently uses
   "no indent, start in column 0" would need indenting. (This would
   be a lot of change to our current docs text.)
 * it doesn't say in the spec, but I guess that spaces between
   the colon and start of line 1 text are not significant.

The advantage would be a bit more consistency with rST syntax
otherwise; the disadvantage is that we have a *lot* of text
that uses the "start in column 0" format, like this:

# @QCryptoBlockOptionsBase:
#
# The common options that apply to all full disk
# encryption formats

and we'd need to reindent it all. My view is that trying to
look more like rST indent isn't sufficiently useful to be
worth having to change all that.

> This is something people may actually write.

Indeed, they have :-)

thanks
-- PMM