@samitouri / QOSamiQemu / commits / 9606414d46

tests/qapi: generate output in source order

Rewrite the test doc generator to produce output in source order instead of arbitrarily by section name. This patch removes our last use of the "body" field, which has an effect on how the sections of each test documention block are printed. We now print the name of the section followed by the section text for all sections except Members and Features, which are printed as "Member=%s" or "Feature=%s" followed by the section text, respectively. This patch is motivated by a desire to move the QAPIDoc API away from named fields for specific sections in a bid to force all users to simply iterate through all_sections in order, instead - and to remove the named subsections. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20260611042332.482979-3-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>

John Snow committed Jun 11, 2026 at 00:23 UTC 9606414d4658252ba893423fe6579023bca293e3
2 files changed +48 -48
tests/qapi-schema/doc-good.out
+41 -41
@@ -54,15 +54,15 @@ event EVT_BOXED Object
54 boxed=True
55 feature feat3
56 doc freeform
57 - body=
57 + Plain
58 *******
59 Section
60 *******
61 doc freeform
62 - body=
62 + Plain
63 Just text, no heading.
64 doc freeform
65 - body=
65 + Plain
66 Subsection
67 ==========
68
@@ -106,84 +106,84 @@ Examples:
106 - *verbatim*
107 - {braces}
108 doc symbol=Enum
109 - body=
109 + Plain
110
111 - arg=one
111 + Member=one
112 The _one_ {and only}, description on the same line
113 - arg=two
113 + Member=two
114
115 - feature=enum-feat
115 + Feature=enum-feat
116 Also _one_ {and only}
117 - feature=enum-member-feat
117 + Feature=enum-member-feat
118 a member feature
119 - section=Plain
119 + Plain
120 @two is undocumented
121 doc symbol=Base
122 - body=
122 + Plain
123
124 - arg=base1
124 + Member=base1
125 description starts on a new line,
126 minimally indented
127 doc symbol=Variant1
128 - body=
128 + Plain
129 A paragraph
130
131 Another paragraph
132
133 @var1 is undocumented
134 - arg=var1
134 + Member=var1
135
136 - feature=variant1-feat
136 + Feature=variant1-feat
137 a feature
138 - feature=member-feat
138 + Feature=member-feat
139 a member feature
140 doc symbol=Variant2
141 - body=
141 + Plain
142
143 doc symbol=Object
144 - body=
144 + Plain
145
146 - feature=union-feat1
146 + Feature=union-feat1
147 a feature
148 doc symbol=Alternate
149 - body=
149 + Plain
150
151 - arg=i
151 + Member=i
152 description starts on the same line
153 remainder indented the same
154 @b is undocumented
155 - arg=b
155 + Member=b
156
157 - feature=alt-feat
157 + Feature=alt-feat
158 a feature
159 doc freeform
160 - body=
160 + Plain
161 Another subsection
162 ==================
163 doc symbol=cmd
164 - body=
164 + Plain
165
166 - arg=arg1
166 + Member=arg1
167 description starts on a new line,
168 indented
169 - arg=arg2
169 + Member=arg2
170 description starts on the same line
171 remainder indented differently
172 - arg=arg3
172 + Member=arg3
173
174 - feature=cmd-feat1
174 + Feature=cmd-feat1
175 a feature
176 - feature=cmd-feat2
176 + Feature=cmd-feat2
177 another feature
178 - section=Plain
178 + Plain
179 .. note:: @arg3 is undocumented
180 - section=Returns
180 + Returns
181 @Object
182 - section=Errors
182 + Errors
183 some
184 - section=Todo
184 + Todo
185 frobnicate
186 - section=Plain
186 + Plain
187 .. admonition:: Notes
188
189 - Lorem ipsum dolor sit amet
@@ -207,23 +207,23 @@ Examples::
207
208 Note::
209 Ceci n'est pas une note
210 - section=Since
210 + Since
211 2.10
212 doc symbol=cmd-boxed
213 - body=
213 + Plain
214 If you're bored enough to read this, go see a video of boxed cats
215 - feature=cmd-feat1
215 + Feature=cmd-feat1
216 a feature
217 - feature=cmd-feat2
217 + Feature=cmd-feat2
218 another feature
219 - section=Plain
219 + Plain
220 .. qmp-example::
221
222 -> "this example"
223
224 <- ... has no title ...
225 doc symbol=EVT_BOXED
226 - body=
226 + Plain
227
228 - feature=feat3
228 + Feature=feat3
229 a feature
tests/qapi-schema/test-qapi.py
+7 -7
@@ -19,6 +19,7 @@ import sys
19 from io import StringIO
20
21 from qapi.error import QAPIError
22 +from qapi.parser import QAPIDoc
23 from qapi.schema import QAPISchema, QAPISchemaVisitor
24
25
@@ -116,13 +117,12 @@ def test_frontend(fname):
117 print('doc symbol=%s' % doc.symbol)
118 else:
119 print('doc freeform')
119 - print(' body=\n%s' % doc.body.text)
120 - for arg, section in doc.args.items():
121 - print(' arg=%s\n%s' % (arg, section.text))
122 - for feat, section in doc.features.items():
123 - print(' feature=%s\n%s' % (feat, section.text))
124 - for section in doc.sections:
125 - print(' section=%s\n%s' % (section.kind, section.text))
120 + for section in doc.all_sections:
121 + if isinstance(section, QAPIDoc.ArgSection):
122 + print(' %s=%s' % (section.kind, section.name))
123 + else:
124 + print(' %s' % section.kind)
125 + print(section.text)
126
127
128 def open_test_result(dir_name, file_name, update):