Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions

[Markus Armbruster]

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

> On Tue, 29 Sep 2020 at 13:35, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > Update the documentation of QAPI document comment syntax to match
>> > the new rST backend requirements. The principal changes are:
>> >  * whitespace is now significant,
>>
>> Well, differently significant :)  Anyway, close enough.
>>
>> >                                   and multiline definitions
>> >    must have their second and subsequent lines indented to
>> >    match the first line
>> >  * general rST format markup is permitted, not just the small
>> >    set of markup the old texinfo generator handled. For most
>> >    things (notably bulleted and itemized lists) the old format
>> >    is the same as rST was.
>>
>> "was the same as rST is"?
>
> Yes :-)

Can fix in my tree.

>
>> v5 had
>>
>>   @@ -899,6 +915,12 @@ commands and events), member (for structs and 
>> unions), branch (for
>>    alternates), or value (for enums), and finally optional tagged
>>    sections.
>>
>>   +Descriptions of arguments can span multiple lines; if they
>>   +do then the second and subsequent lines must be indented
>>   +to line up with the first character of the first line of the
>>   +description. The parser will report a syntax error if there
>>   +is insufficient indentation.
>>   +
>>    FIXME: the parser accepts these things in almost any order.
>>    FIXME: union branches should be described, too.
>>
>> I questioned the value of the last sentence.  You dropped both.
>> Intentional?
>
> I moved the first sentence to patch 5 in v6 (ie to the patch
> which updates parser.py to enforce those indentation restrictions),
> so as to make patches 1..5 suitable for merging even if we needed
> to respin the second half of the series.

I see.

>> > @@ -937,6 +950,16 @@ multiline argument descriptions.
>> >  A 'Since: x.y.z' tagged section lists the release that introduced the
>> >  definition.
>> >
>> > +The text of a section can start on a new line, in
>> > +which case it must not be indented at all.  It can also start
>> > +on the same line as the 'Note:', 'Returns:', etc tag.  In this
>> > +case if it spans multiple lines then second and subsequent
>> > +lines must be indented to match the first.
>
> I also moved this paragraph into patch 5 (where it appears just
> above the "A 'Since:..." text you can see in the context here)
> but forgot to delete the copy of it here, so at this point it is
> duplicate text and should not be in this patch. Oops.
>
>> > +
>> > +An 'Example' or 'Examples' section is automatically rendered
>> > +entirely as literal fixed-width text.  In other sections,
>> > +the text is formatted, and rST markup can be used.
>
> (This patch is the right place for this paragraph.)

Thanks!

Reviewed-by: Markus Armbruster <armbru@redhat.com>