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

[Peter Maydell]

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


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

> > @@ -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
-- PMM