Re: [PATCH RFC 2/2] qapi: Make section headings start a new doc comment block

[Peter Maydell]

On Fri, 20 Mar 2020 at 09:18, Markus Armbruster <address@hidden> wrote:
>
> Our current QAPI doc-comment markup allows section headers (introduced
> with a leading '=' or '==') anywhere in a free-form documentation
> comment.  This works for Texinfo because the generator simply prints a
> Texinfo section command at that point in the output stream.  For rST
> generation, since we're assembling a tree of docutils nodes, this is
> awkward because a new section implies starting a new section node at
> the top level of the tree and generating text into there.
>
> Make section headers start a new free-form documentation block, so the
> future rST document generator doesn't have to look at every line in
> free-form blocks and handle headings in odd places.
>
> This change makes no difference to the generated Texinfo.

I think this does make things easier for rST generation
(which now can say "if the first line in the freeform doc
is a section heading, do section heading stuff, discard that
line, process rest of freeform doc as normal"), so on
that basis I like it.

I do kind of think it would be overall nicer to go further and
say "section headings are special and not part of free-form doc
comments at all" (both for the doc-comment author by mandating
that they be standalone, and for the consumer of parsed info
by separating section headings out from free-form doc comment
rather than requiring the consumer to say "is this line heading
syntax?"), but that would be more change, so pragmatically
I'm happy if we just do what this patch suggests.

thanks
-- PMM