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

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Aug 27, 2026 at 9:39 AM Daniel P. Berrangé <berrange@redhat.com> wrote:
>>
>> On Thu, Aug 27, 2026 at 03:09:35PM +0200, Markus Armbruster wrote:
>> > 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:
>>
>> Yes, I just didn't see the connection from that, to the use
>> of indent.

Writing good cover letters is hard.

>> >
>> >     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.
>>
>> So IIUC, you're saying that we are going to rely on indentation
>> to distinguish introduction from details ?

Yes.

We are already relying on indentation elsewhere.  For instance:

    # @fatal: if set, the image is marked corrupt and therefore unusable
    #     after this event and must be repaired (Since 2.2; before, every
    #     `BLOCK_IMAGE_CORRUPTED` event was fatal)
    #
    # .. note:: If action is "stop", a `STOP` event will eventually follow
    #    the `BLOCK_IO_ERROR` event.

The description of @fatal is indented.  A non-indented line ends it.
The non-indented line happens to be a Sphinx directive here, but that's
immaterial (the QAPI doc comment parser does not attempt to parse ReST).

>> > 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?
>>
>> As an author, how substantive is "Intro" expected to be? I guess on
>> QAPI docs I've written I've not ever been aware of there even being
>> a distinct concept of Intro vs Details to think about. It is all just
>> some lines of prose to me.

That's deceptive :)

Consider

    ##
    # @HV_BALLOON_STATUS_REPORT:
    #
    # Emitted when the hv-balloon driver receives a "STATUS" message from
    # the guest.
    #
    # .. note:: This event is rate-limited.
    #
    # Since: 8.2
    #
    # .. qmp-example::
    #
    #     <- { "event": "HV_BALLOON_STATUS_REPORT",
    #          "data": { "committed": 816640000, "available": 3333054464 },
    #          "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
    ##
    { 'event': 'HV_BALLOON_STATUS_REPORT',
      'data': 'HvBalloonInfo' }

Rendered documentation looks like

    Event HV_BALLOON_STATUS_REPORT (Since: 8.2)

       Emitted when the hv-balloon driver receives a "STATUS" message from
       the guest.

       Note:

         This event is rate-limited.

       Members:
          * The members of "HvBalloonInfo".

       Example::

          <- { "event": "HV_BALLOON_STATUS_REPORT",
               "data": { "committed": 816640000, "available": 3333054464 },
               "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }

Where does "Members:" come from?  Its generated.

If we move "Since:" to the end of the doc comment, we instead get

    Event HV_BALLOON_STATUS_REPORT (Since: 8.2)

       Emitted when the hv-balloon driver receives a "STATUS" message from
       the guest.

       Note:

         This event is rate-limited.

       Example::

          <- { "event": "HV_BALLOON_STATUS_REPORT",
               "data": { "committed": 816640000, "available": 3333054464 },
               "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }

       Members:
          * The members of "HvBalloonInfo".

This one is clearly bad.  The fact that an innocent move of "Since:" can
make the rendered docs worse is a defect in the QAPI doc system.

But even the first version isn't quite what we want.  We want Members:
further up, like this:

    Event HV_BALLOON_STATUS_REPORT (Since: 8.2)

       Emitted when the hv-balloon driver receives a "STATUS" message from
       the guest.

       Members:
          * The members of "HvBalloonInfo".

       Note:

         This event is rate-limited.

       Example::

          <- { "event": "HV_BALLOON_STATUS_REPORT",
               "data": { "committed": 816640000, "available": 3333054464 },
               "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }

Now we're ready to discuss "intro" vs. "details.  Their separation
matters in this example, because the generated "Members:" go right after
"intro".

The root of the problem is a syntactic ambiguity.  "Intro" is commonly
followed by some "@argument: ...", "Return:", "Error:", or similar.  But
these are all optional.  When they're absent, the what's "intro" and
what's "details" is syntactically ambiguous.

The doc comment I used as example abuses "Since:" to separate them.

> In most cases, not very substantial. For commands and events, it *can*
> be quite a bit more substantial. For structs, enums, etc it is almost
> always laughably trivial.
>
> When the syntactical delineation of intro is complete, further QAPI
> parser changes will make it even more obvious: any free text that
> exists between the intro and the other sections will be flagged as an
> error, where you will be urged to move any detail text to below the
> metadata fields. This physical relocation will help suggest to the
> documentation author what goes "above the fold" and what goes "below
> the fold", so to speak.

This is part of our slow move towards a standard doc comment structure,
ultimately enforced by the generator.  Standard structure helps readers.

>> My only alternative idea to indentation would be to declare that the
>> "Intro" is always the 1st paragraph of text and anything beyond that
>> is the "Details". That might match up with the way that contributors
>> naturally write text where the 1st paragraph conveys the key idea,
>> such that they dno't need to think about Intro vs Details as a
>> concept.
>
> Yeah, that's roughly the idea; and some prototypes used this idea in
> the past - but Markus wanted an explicit, obvious delineation
> precisely to *force* documentation authors to think about the split.
> It has implications for what gets generated into the documentation and
> in which scenarios.

"First paragraph is intro" is workable syntax.  It restricts "intro" to
a single paragraph", which is unlikely to be a serious problem.
However, the restriction is easy to forget.  If you write two paragraphs
(because "it is all just some lines of prose"), the rendering can
surprise you, in a bad way.

Having to indent "intro" forces you to be explicit, and avoids
surprises.

> I do usually try to make my upgrades "invisible" to the user, but in
> this case I believe we are erring on the side of "explicit is better
> than implicit" because of the implications of the text not always
> being copied in a precisely straightforward manner to the HTML docs.

Blame it on me: I pushed John towards explicit.

> I will address the subtleties of this issue when the inliner is being
> merged by updating a documentation writer's guide that covers what
> goes where and why. For now, we are just trying to do the bulk
> conversion.
>
>>
>> With regards,
>> Daniel
>
> --js