John Snow <[email protected]> writes:
> On Fri, Mar 20, 2026, 8:24 AM Markus Armbruster <[email protected]> wrote:
>
>> John Snow <[email protected]> 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 <[email protected]>
>>
>> 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.
No worries!
> 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.
Turns out we use the first section (i.e. INTRO) for describing the thing
being defined. Inlining such descriptions results in nonsense. For
instance, here's SevGuestProperties and its base SevGuestProperties:
##
# @SevCommonProperties:
#
# Properties common to objects that are derivatives of sev-common.
#
[...]
##
# @SevGuestProperties:
#
# Properties for sev-guest objects.
#
# @dh-cert-file: guest owners DH certificate (encoded with base64)
#
[...]
Inlining the base as you originally thought would result in something
like
Object SevGuestProperties (Since: 2.12)
Properties for sev-guest objects.
Properties common to objects that are derivatives of sev-common.
Members: * dh-cert-file (string, optional) -- guest owners DH
certificate (encoded with base64)
The intro paragraph inlined from the base is nonsense.
We either stop writing such descriptions (ugh), or we drop them on
inlining. If we drop, code needs to recognize them. The only method I
can see is to assume INTRO is description.
Now, the QAPI generator cannot stop people from putting stuff in INTRO
is *not* description and *should* be inlined. This is a risk we will
have to accept to gain the benefits of inlining.
For the inliner's initial merge, we'll want to review all the INTRO
sections the inliner drops. If almost all of them are fine, the risk is
low.
> 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.
Yes.
I think we'll want to at least hint at this in the final commit message.
The full story would be too much, I guess.
>> 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.
Have you tried swapping the patches?
If that's bothersome, squashing them together may well do.
>> 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.
We can handwave these two away, but the issue persists until the next
patch.
Consider this change to the test before the series:
diff --git a/tests/qapi-schema/doc-good.json
b/tests/qapi-schema/doc-good.json
index fac13425b7..4d586b043f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -169,6 +169,8 @@
#
# Returns: @Object
#
+# plain in the middle
+#
# Errors: some
#
# TODO: frobnicate
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 04a5507264..040e901474 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -179,6 +179,8 @@ another feature
.. note:: @arg3 is undocumented
section=Returns
@Object
+ section=Plain
+plain in the middle
section=Errors
some
section=Todo
The current patch then acquires another hunk:
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 04e29e8d50..28abb1d98e 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -179,6 +179,8 @@ another feature
.. note:: @arg3 is undocumented
section=Returns
@Object
+ section=Details
+plain in the middle
section=Errors
some
section=Todo
> 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.)
[...]
