Re: [PATCH 1/8] qapi: differentiate "intro" and "details" sections

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 6791 bytes --]

On Fri, Mar 20, 2026, 8:24 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > This patch begins distinguishing "Plain" sections as being either
> > "Intro" or "Details" sections for the purpose of knowing when/where/how
> > to inline those sections.
> >
> > The Intro section is always the first section of any doc block. It may
> > be empty or any number of paragraphs. It is interrupted by any other
> > non-plaintext section, i.e.; Members, Features, Errors, Returns, Since,
> > and TODO.
> >
> > The details section, when present, is either the last section or the
> > second-to-last section when a "Since:" section is present. It consists
> > of any plain text in the doc block that follows any named sections if
> > present.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> The commit message explains what kinds INTRO and DETAILS are, but not
> why they're useful.  My guess:
>

Right, my apologies. Leaning on you having some existing knowledge here,
and also going light on details because the series is still obviously in
flux.

Let me elaborate on the motivations here...


> 1. Represent the future "Details:" marker: the plain section before it
> is of kind INTRO, the one afterwards is of kind DETAILS.
>

Yes.


> 2. Future programming convenience?  With just PLAIN, code may have to
> understand the section's context to make decisions, and with INTRO and
> DETAILS is doesn't.
>
> Guess close enough?
>

Pretty much.

Originally, I thought I'd inline things like this:

Intro (child)
Intro (parent)
...other sections...
Details (parent)
Details (child)

Last time we went over this, you mused that there was likely never a
sufficient reason to actually inline the intro. I recall believing and
accepting this.

So functionally what this does for us is:

(1) Explicitly delineate what comes before the tabular section of the docs
(members, Returns, Errors, features) and what comes after.

(2) Explicitly defines what will not be inlined.


> The commit message covers PLAIN sections at the beginning and at the end
> (modulo Since:).  It doesn't cover PLAIN sections between tagged
> sections / member descriptions.  You disallow these in PATCH 2.  You can
> either cover them here, or get rid of them by swapping PATCH 1 and 2.
>

Sure. For now they're separated just to separate concerns in review, but if
you believe both should be all-at-once, that's fine too. I think there's
not a regression by separating it, though. It's just a semantic change from
details meaning "anything after the intro" to "specifically the closing
section". The intermediate meaning exists for only one patch.


> Hmm, is your description of DETAILS accurate?  Looks like it isn't; see
> my review of tests/qapi-schema/doc-good.out below.
>

Whoops, future-think. It winds up being true, but isn't true yet as of this
commit. Well, almost. See below.


> > ---
> >  docs/sphinx/qapidoc.py         |  2 +-
> >  scripts/qapi/parser.py         | 35 +++++++++++++++++++++++-----------
> >  tests/qapi-schema/doc-good.out |  8 ++++----
> >  3 files changed, 29 insertions(+), 16 deletions(-)
>
> [Skipping the Python code in my first pass...]
>
> > diff --git a/tests/qapi-schema/doc-good.out
> b/tests/qapi-schema/doc-good.out
> > index 04a55072646..04e29e8d50f 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line
> >  Also _one_ {and only}
> >      feature=enum-member-feat
> >  a member feature
> > -    section=Plain
> > +    section=Details
> >  @two is undocumented
>
> The section containing "@two is undocumented" changes from PLAIN to
> DETAILS.  Doc source:
>
>     ##
>     # @Enum:
>     #
>     # @one: The _one_ {and only}, description on the same line
>     #
>     # Features:
>     # @enum-feat: Also _one_ {and only}
>     # @enum-member-feat: a member feature
>     #
>     # @two is undocumented
>     ##
>
> It is at the end.  Good.
>
> >  doc symbol=Base
> >      body=
> > @@ -175,7 +175,7 @@ description starts on the same line
> >  a feature
> >      feature=cmd-feat2
> >  another feature
> > -    section=Plain
> > +    section=Details
> >  .. note:: @arg3 is undocumented
>
> The section containing "@arg3 is undocumented" changes from PLAIN to
> DETAILS.  Doc source:
>
> Doc source:
>
>     ##
>     # @cmd:
>     #
>     # @arg1:
>     #     description starts on a new line,
>     #     indented
>     #
>     # @arg2: description starts on the same line
>     #     remainder indented differently
>     #
>     # Returns: @Object
>     #
>     # Errors: some
>     #
>     # Features:
>     # @cmd-feat1: a feature
>     # @cmd-feat2: another feature
>     #
>     # .. note:: @arg3 is undocumented
>     #
>     # TODO: frobnicate
>     #
>
> It is *not* at the end.  Is the commit message inaccurate?
>

Ah. I wasn't considering TODO... Since it is a comment I mentally elided it.

What I mean to say is that Details is (will be) essentially the last
content section that is actually rendered.

In the HTML, it will always be last if present because both TODO and Since
are actually entirely removed from the flow of the document.

Though as we both point out, what i write is not technically true here. (It
can currently be an intermediate section AND Since is not the only section
that may follow it.)


> >      section=Returns
> >  @Object
> > @@ -183,7 +183,7 @@ another feature
> >  some
> >      section=Todo
> >  frobnicate
> > -    section=Plain
> > +    section=Details
> >  .. admonition:: Notes
> >
> >   - Lorem ipsum dolor sit amet
>     - Ut enim ad minim veniam
>
>     [some section body text elided for brevity...]
>
>    Note::
>        Ceci n'est pas une note
>        section=Since
>    2.10
>
> The section starting with the adminition and ending after "Ceci n'est
> pas une note" changes from PLAIN to DETAILS.  Doc source continued:
>
>     # .. admonition:: Notes
>     #
>     #  - Lorem ipsum dolor sit amet
>     #  - Ut enim ad minim veniam
>     #
>     [same text elided...]
>     #
>     # Note::
>     #     Ceci n'est pas une note
>     #
>     # Since: 2.10
>     ##
>
> It is second-to-last, and the last section is SINCE.  Good.
>
> > @@ -216,7 +216,7 @@ If you're bored enough to read this, go see a video
> of boxed cats
> >  a feature
> >      featurec=md-feat2
> >  another feature
> > -    section=Plain
> > +    section=Details
> >  .. qmp-example::
> >
> >     -> "this example"
>
> This one is also at the end.  Good.
>
>

[-- Attachment #2: Type: text/html, Size: 10222 bytes --]