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

[Markus Armbruster]

Peter Maydell <address@hidden> writes:

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

Good.

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

I think there are two separate issues: doc comment syntax and internal
representation.

Our internal representation reflects the input's flat structure: one
comment block after the other.  I wish it reflected the document's tree
structure instead, but I can't justify the effort to rework it.

What to put into syntax and what to leave to style is often debatable.
Putting headings into their own block makes them stand out even more,
which may be useful.  Baking that into the syntax feels a bit oppressive
to me.  Sometimes a bit of oppression can buy enough consistency to be
worth it.

Thanks!