On 3/9/20 8:43 AM, Peter Maydell wrote: > Our current QAPI doc-comment markup allows section headers > (introduced with a leading '=' or '==') anywhere in any documentation > comment. This works for texinfo because the texi generator simply > prints a texinfo heading directive 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. > > New section headings in the middle of the documentation of a command > or event would be pretty nonsensical, and in fact we only ever output > new headings using 'freeform' doc comment blocks whose only content > is the single line of the heading, with two exceptions, which are in > the introductory freeform-doc-block at the top of > qapi/qapi-schema.json. > > Split that doc-comment up so that the heading lines are in their own > doc-comment. This will allow us to tighten the specification to > insist that heading lines are always standalone, rather than > requiring the rST document generator to look at every line in a doc > comment block and handle headings in odd places. > > This change makes no difference to the generated texi. > > Signed-off-by: Peter Maydell <peter.mayd...@linaro.org> > --- > qapi/qapi-schema.json | 12 +++++++++--- > 1 file changed, 9 insertions(+), 3 deletions(-)
Reviewed-by: Richard Henderson <richard.hender...@linaro.org> r~
