qapi: add doc comment "Intro" section parsing
Add parsing for explicit Intro section syntax. A side effect of this patch is that we will (currently) always create an empty Intro section, similar to how we used to have an empty Plain section. The tests are adjusted accordingly, rendered document output does not change at all. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20260611042332.482979-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
John Snow committed
Jun 11, 2026 at 00:23 UTC
ebb49d4bb6bcc4f97401fabf3310937d44a2226b
3 files changed
+27
-11
docs/devel/qapi-code-gen.rst
+7
-9
@@ -984,11 +984,11 @@ definition it documents.
984
When documentation is required (see pragma_ 'doc-required'), every
985
definition must have documentation.
986
987
-Definition documentation starts with a line naming the definition,
988
-followed by an optional overview, a description of each argument (for
989
-commands and events), member (for structs and unions), branch (for
990
-alternates), or value (for enums), a description of each feature (if
991
-any), and finally optional tagged sections.
987
+Definition documentation starts with a description naming the
988
+definition with an optional indented overview, a description of each
989
+argument (for commands and events), member (for structs and unions),
990
+branch (for alternates), or value (for enums), a description of each
991
+feature (if any), and finally optional tagged sections.
992
993
Descriptions start with '\@name:'. The description text must be
994
indented like this::
@@ -1093,8 +1093,7 @@ Examples of complete definition documentation::
1093
1094
##
1095
# @BlockStats:
1096
- #
1097
- # Statistics of a virtual block device or a block backing device.
1096
+ # Statistics of a virtual block device or a block backing device.
1097
#
1098
# @device: If the stats are for a virtual block device, the name
1099
# corresponding to the virtual block device.
@@ -1111,8 +1110,7 @@ Examples of complete definition documentation::
1110
1111
##
1112
# @query-blockstats:
1114
- #
1115
- # Query the @BlockStats for all virtual block devices.
1113
+ # Query the @BlockStats for all virtual block devices.
1114
#
1115
# @query-nodes: If true, the command will query all the block nodes
1116
# ... explain, explain ...
scripts/qapi/parser.py
+2
-2
@@ -542,8 +542,8 @@ class QAPISchemaParser:
542
if not symbol:
543
raise QAPIParseError(self, "name required after '@'")
544
doc = QAPIDoc(info, symbol)
545
- self.accept(False)
546
- line = self.get_doc_line()
545
+ doc.all_sections.append(QAPIDoc.Section(info, QAPIDoc.Kind.INTRO))
546
+ line = self.get_doc_indented(doc)
547
no_more_args = False
548
549
while line is not None:
tests/qapi-schema/doc-good.out
+18
@@ -106,6 +106,8 @@ Examples:
106
- *verbatim*
107
- {braces}
108
doc symbol=Enum
109
+ Intro
110
+
111
Member=one
112
The _one_ {and only}, description on the same line
113
Member=two
@@ -117,10 +119,14 @@ a member feature
119
Plain
120
@two is undocumented
121
doc symbol=Base
122
+ Intro
123
+
124
Member=base1
125
description starts on a new line,
126
minimally indented
127
doc symbol=Variant1
128
+ Intro
129
+
130
Plain
131
A paragraph
132
@@ -134,10 +140,16 @@ a feature
140
Feature=member-feat
141
a member feature
142
doc symbol=Variant2
143
+ Intro
144
+
145
doc symbol=Object
146
+ Intro
147
+
148
Feature=union-feat1
149
a feature
150
doc symbol=Alternate
151
+ Intro
152
+
153
Member=i
154
description starts on the same line
155
remainder indented the same
@@ -151,6 +163,8 @@ doc freeform
163
Another subsection
164
==================
165
doc symbol=cmd
166
+ Intro
167
+
168
Member=arg1
169
description starts on a new line,
170
indented
@@ -198,6 +212,8 @@ Note::
212
Since
213
2.10
214
doc symbol=cmd-boxed
215
+ Intro
216
+
217
Plain
218
If you're bored enough to read this, go see a video of boxed cats
219
Feature=cmd-feat1
@@ -211,5 +227,7 @@ another feature
227
228
<- ... has no title ...
229
doc symbol=EVT_BOXED
230
+ Intro
231
+
232
Feature=feat3
233
a feature