John Snow <[email protected]> writes:
> On Thu, Aug 27, 2026 at 9:39 AM Daniel P. Berrangé <[email protected]>
> wrote:
>>
>> On Thu, Aug 27, 2026 at 03:09:35PM +0200, Markus Armbruster wrote:
>> > Daniel P. Berrangé <[email protected]> writes:
>> >
>> > > On Wed, Aug 26, 2026 at 03:37:58PM -0400, John Snow wrote:
>> > >> Signed-off-by: John Snow <[email protected]>
>> > >> ---
>> > >> 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: <[email protected]>
>> > https://lore.kernel.org/qemu-devel/[email protected]/
>> >
>> > 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
