[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc
From: |
Richard Henderson |
Subject: |
Re: [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc-comment blocks |
Date: |
Tue, 10 Mar 2020 23:06:38 -0700 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
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 <address@hidden>
> ---
> qapi/qapi-schema.json | 12 +++++++++---
> 1 file changed, 9 insertions(+), 3 deletions(-)
Reviewed-by: Richard Henderson <address@hidden>
r~
- [PATCH v4 00/18] Convert QAPI doc comments to generate rST instead of texinfo, Peter Maydell, 2020/03/09
- [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc-comment blocks, Peter Maydell, 2020/03/09
- [PATCH v4 03/18] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/03/09
- [PATCH v4 05/18] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/03/09
- [PATCH v4 04/18] tests/qapi/doc-good.json: Clean up markup, Peter Maydell, 2020/03/09
- [PATCH v4 01/18] qapi/migration.json: Fix indentation, Peter Maydell, 2020/03/09