Re: [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc-comment blocks

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> 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.maydell@linaro.org>
> ---
>  qapi/qapi-schema.json | 12 +++++++++---
>  1 file changed, 9 insertions(+), 3 deletions(-)
>
> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index fe980ce4370..ff5aea59451 100644
> --- a/qapi/qapi-schema.json
> +++ b/qapi/qapi-schema.json
> @@ -1,7 +1,9 @@
>  # -*- Mode: Python -*-
>  ##
>  # = Introduction
> -#
> +##
> +
> +##
>  # This document describes all commands currently supported by QMP.
>  #
>  # Most of the time their usage is exactly the same as in the user Monitor, this
> @@ -25,9 +27,13 @@
>  #
>  # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
>  # detailed information on the Server command and response formats.
> -#
> +##
> +
> +##
>  # = Stability Considerations
> -#
> +##
> +
> +##
>  # The current QMP command set (described in this file) may be useful for a
>  # number of use cases, however it's limited and several commands have bad
>  # defined semantics, specially with regard to command completion.

The restriction you add is tolerable.  But how does the doc generator
behave when I get it wrong?  The test case for getting it wrong is
tests/qapi-schema/doc-bad-section.json.

In current master (commit f57587c7d47b35b2d9b31def3a74d81bdb5475d7),

    $ scripts/qapi-gen.py tests/qapi-schema/doc-bad-section.json 

produces this qapi-doc.texi:

    @c AUTOMATICALLY GENERATED, DO NOT MODIFY


    @deftp {Enum} Enum

    @subsection Produces @strong{invalid} texinfo

    @b{Values:}
    @table @asis
    @item @code{one}
    The @emph{one} @{and only@}
    @item @code{two}
    Not documented
    @end table
    @code{two} is undocumented

    @end deftp

This is invalid Texinfo:

    $ makeinfo qapi-doc.texi 
    qapi-output-master/qapi-doc.texi:4: warning: entry for index `tp' outside of any node
    qapi-output-master/qapi-doc.texi:6: @subsection seen before @end deftp
    qapi-output-master/qapi-doc.texi:17: unmatched `@end deftp'
    [Exit 1 ]

Ignore the warning, it's due to the harmlessly lazy test case.

A developer who puts a section heading in the wrong place in the schema
gets to divine his mistake from makeinfo's error messages.  Not nice.

After your rST conversion[*], ...  Well, I tried to figure out how to
build .html from tests/qapi-schema/doc-bad-section.json, but failed.
Alright, use a heavier hammer: append that file to qapi-schema.json.
Build succeeds, and produces a qemu-qmp-ref.7 that /usr/bin/man renders
like this:

       Enum (Enum)
           == No good here

       Values
           one    The _one_ {and only}

           two    Not documented
           two is undocumented

I consider this even worse than before.

With my "[PATCH 1/2] qapi: Reject section markup in definition
documentation", qapi-gen.py rejects it cleanly:

    tests/qapi-schema/doc-bad-section.json:5:1: unexpected '=' markup in
    definition documentation

I believe it won't hinder your .rST conversion work.  It might even
help.  Maybe only together with PATCH 2/2, but that's for you to decide.


[*] Fetched from
https://git.linaro.org/people/peter.maydell/qemu-arm.git
sphinx-conversions