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

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> 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

The Perl of ASCII-based markups...

> expecting a block-quote). That renders sufficiently close to correct
> that I hadn't noticed it.

Understandable :)

> 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.)

Agree.

> 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.

We use @FOO: for two distinct things:

1. Right at the beginning of a comment block, it makes the comment block
a definition doc block for symbol FOO.

2. At the beginning of an argument section, it names the argument /
member being documented.

Example:

    ##
    # @QCryptoBlockOptionsBase:                         <-- 1.
    #
    # The common options that apply to all full disk
    # encryption formats
    #
    # @format: the encryption format                    <-- 2.
    #
    # Since: 2.6
    ##

We could switch just 2. to reST field list syntax, and either keep 1. as
is, or switch it to some other reST markup that works for us.

But even if we want this, we should do it on top, to avoid complicating
and delaying this series.

>> This is something people may actually write.
>
> Indeed, they have :-)
>
> thanks
> -- PMM