On Fri, 20 Mar 2020 at 09:18, Markus Armbruster <arm...@redhat.com> 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
