Re: [PATCH v3 01/43] qapi: convert trivial intro sections for error.json

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Wed, Aug 26, 2026 at 03:37:58PM -0400, John Snow wrote:
>> Signed-off-by: John Snow <jsnow@redhat.com>
>> ---
>>  qapi/error.json | 3 +--
>>  1 file changed, 1 insertion(+), 2 deletions(-)
>> 
>> diff --git a/qapi/error.json b/qapi/error.json
>> index 54cb02fb880..a53b13e55c9 100644
>> --- a/qapi/error.json
>> +++ b/qapi/error.json
>> @@ -9,8 +9,7 @@
>>  
>>  ##
>>  # @QapiErrorClass:
>> -#
>> -# QEMU error classes
>> +#     QEMU error classes
>
> Where is this need for indent coming from ?  From the POV of someone
> writing comments, the need to indent the introductory text like this
> feels very counter-intuitive, an exception from any other inline
> docs syntax I've typically used. Is there any way we can avoid this ?

The cover letter explains the need:

    This is being done primarily for the benefit of the forthcoming
    "inliner", a feature for the rendered HTML QMP documentation that
    seeks to "inline" QMP command argument documentation into the argument
    list for each command.

    There are two main motives here:

    (1) We want the split between the "introduction" and "details"
        sections to be mechanically obvious, so that auto-generated or
        inlined documentation has a well-defined, obvious spot to go.

    (2) We do not want to inline irrelevant, introductory text describing
        structures to be copied into command documentation.

But the need actually exists already, the inliner merely grows it.

Let me elaborate using an example: query-memory-size-summary

Its doc comment:

    ##
    # @query-memory-size-summary:
    #
    # Return the amount of initially allocated and present hotpluggable
    # (if enabled) memory in bytes.
    #
    # TODO: This line is a hack to separate the example from the body
    #
    # .. qmp-example::
    #
    #     -> { "execute": "query-memory-size-summary" }
    #     <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
    #
    # Since: 2.11
    ##

Looks like this in the generated QEMU QMP Reference Manual:

    Command query-memory-size-summary (Since: 2.11)

       Return the amount of initially allocated and present hotpluggable
       (if enabled) memory in bytes.

       Return:
          "MemoryInfo"

       Example::

          -> { "execute": "query-memory-size-summary" }
          <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }

The "Return:" part is inserted by the generator.  Where?  The order we
want is roughly

    Intro (a brief description)
    Members / Arguments
    Returns
    Errors
    Features
    Details (additional information, examples, ...)
    Since
    
Members / Arguments, Returns, Errors, and Features are all optional.
They are in fact all absent in query-memory-size-summary.  This makes
Intro and Details bleed together.

The TODO line keeps them separate, because it's a section (the doc
comment syntax is a sequence of sections, in this case Intro, TODO,
Details).  Not only is abusing TODO an ugly hack, it's also easy to
forget.  If we did forget it here, Return would be inserted in at the
very end:

    Command query-memory-size-summary (Since: 2.11)

       Return the amount of initially allocated and present hotpluggable
       (if enabled) memory in bytes.

       Example::

          -> { "execute": "query-memory-size-summary" }
          <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }

       Return:
          "MemoryInfo"

Fortunately, the problem is uncommon: we have just five such TODOs right
now.

Unfortunately, the (still not merged) inliner makes it a lot more
common, and also more serious.

A preparatory series from John added 59 such markers, i.e. about one in
twenty doc comments needed one.  "Such markers" because he didn't abuse
TODO, but created proper syntax for it, namely a Details: line.

Why more serious?  Have a look at netdev_add.  Looks like this in the
generated QEMU QMP Reference Manual:

    Command netdev_add (Since: 0.14)

       Add a network backend.

       Additional arguments depend on the type.

       Arguments:
          * The members of "Netdev".

       [...]

To actually see the arguments, you need to follow the link to type
Netdev.  This is bad UX.  We want the arguments right there, so the
inliner inlines Netdev documentation:

    Object Netdev (Since: 1.2)

       Captures the configuration of a network device.

       Members:
          * **id** ("string") -- identifier for monitor commands.

          * **type** ("NetClientDriver") -- Specify the driver used for
            interpreting remaining arguments.

          * When "type" is "nic": The members of "NetLegacyNicOptions".

       [...]

into netdev_add documentation like this:

    Command netdev_add (Since: 0.14)

       Add a network backend.

       Additional arguments depend on the type.

       Arguments:
          * **id** ("string") -- identifier for monitor commands.

          * **type** ("NetClientDriver") -- Specify the driver used for
            interpreting remaining arguments.

          * When "type" is "nic": The members of "NetLegacyNicOptions".

       [...]

Note that the inliner elided Netdev's Intro "Captures the configuration
of a network device."

However, when Intro and Details bleed together, the inliner elides more
than it should.  I consider that a fairly serious issue.

I'm afraid forgetting to mark the end of Intro with "Details:" would be
a common mistake, easy to miss in review.  So I explored possible
alternatives:

    Subject: Re: [PATCH v2 00/10] qapi: enforce section ordering
    Date: Wed, 15 Apr 2026 11:43:45 +0200
    Message-ID: <87zf341ru6.fsf@pond.sub.org>
    https://lore.kernel.org/qemu-devel/87zf341ru6.fsf@pond.sub.org/

John is working towards "3. Make the end of intro syntactically obvious"
always, specifically "3c. Indent intro like descriptions and tagged
sections" with the ultimate goal to reject unindented Intro.  That way,
we cannot write an Intro with an unclear end.  John, correct me if I'm
accidentally misrepresenting your work.

Questions?  Better ideas?

[...]