On Fri, Mar 20, 2026, 9:47 AM Markus Armbruster <[email protected]> wrote:
> John Snow <[email protected]> writes: > > > This patch prohibits plain documentation sections from appearing between > > "tagged" sections. The two existing uses of this pattern are patched > > out. > > > > This is being done primarily to ensure consistency between the source > > documents and the final, rendered HTML output. Because > > member/feature/returns/error sections will always appear in a visually > > grouped element in the HTML output, prohibiting plain paragraphs between > > those sections ensures ordering consistency between source and the final > > render. > > > > Additionally, prohibiting such "middle" text paragraphs allows us to > > classify all plain text sections as either "intro" or "details" sections, > > because these sections must either appear before structured/tagged > > sections ("intro") or afterwards ("details"). > > > > This keeps the inlining algorithm simpler with fewer "splice" points > > when merging multiple documentation blocks. > > > > Signed-off-by: John Snow <[email protected]> > > --- > > qapi/qom.json | 4 ++-- > > scripts/qapi/parser.py | 17 +++++++++++++++++ > > tests/qapi-schema/doc-good.json | 4 ++-- > > tests/qapi-schema/doc-good.out | 4 ++-- > > tests/qapi-schema/doc-good.txt | 8 ++++---- > > 5 files changed, 27 insertions(+), 10 deletions(-) > > Missing: update to docs/devel/qapi-code-gen.rst. Suggest to put in a > FIXME, so we don't forget. > I will add a FIXME. > Missing: negative test case for the new error. > I will add a FIXME here as well and implement the test once we agree on the approach, implementation, and wording. >
