mirror of
https://github.com/Motorhead1991/qemu.git
synced 2025-12-29 18:50:29 -07:00
323c668934
We have several kinds of sections, and to tell them apart, we use
Section attribute @tag and also the section object's Python type:
type @tag
untagged Section None
@foo: ArgSection 'foo'
Returns: Section 'Returns'
Errors: Section 'Errors'
Since: Section 'Since'
TODO: Section 'TODO'
Note:
* @foo can be a member or a feature description, depending on context.
* tag == 'Since' can be a Since: section or a member or feature
description. If it's a Section, it's the former, and if it's an
ArgSection, it's the latter.
Clean this up as follows. Move the member or feature name to new
ArgSection attribute @name, and replace @tag by enum @kind like this:
type kind name
untagged Section PLAIN
@foo: ArgSection MEMBER 'foo' if member or argument
ArgSection FEATURE 'foo' if feature
Returns: Section RETURNS
Errors: Section ERRORS
Since: Section SINCE
TODO: Section TODO
The qapi-schema tests are updated to account for the new section names;
"TODO" becomes "Todo" and `None` becomes "Plain" there.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-34-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
225 lines
3.6 KiB
Text
225 lines
3.6 KiB
Text
module ./builtin
|
|
object q_empty
|
|
enum QType
|
|
member none
|
|
member qnull
|
|
member qnum
|
|
member qstring
|
|
member qdict
|
|
member qlist
|
|
member qbool
|
|
module doc-good.json
|
|
enum Enum
|
|
member one
|
|
if IFONE
|
|
feature enum-member-feat
|
|
member two
|
|
if IFCOND
|
|
feature enum-feat
|
|
object Base
|
|
member base1: Enum optional=False
|
|
if {'all': ['IFALL1', 'IFALL2']}
|
|
object Variant1
|
|
member var1: str optional=False
|
|
if IFSTR
|
|
feature member-feat
|
|
feature variant1-feat
|
|
object Variant2
|
|
object Object
|
|
base Base
|
|
tag base1
|
|
case one: Variant1
|
|
case two: Variant2
|
|
if {'any': ['IFONE', 'IFTWO']}
|
|
feature union-feat1
|
|
alternate Alternate
|
|
tag type
|
|
case i: int
|
|
case b: bool
|
|
if {'not': {'any': ['IFONE', 'IFTWO']}}
|
|
feature alt-feat
|
|
object q_obj_cmd-arg
|
|
member arg1: int optional=False
|
|
member arg2: str optional=True
|
|
member arg3: bool optional=False
|
|
command cmd q_obj_cmd-arg -> Object
|
|
gen=True success_response=True boxed=False oob=False preconfig=False
|
|
feature cmd-feat1
|
|
feature cmd-feat2
|
|
command cmd-boxed Object -> None
|
|
gen=True success_response=True boxed=True oob=False preconfig=False
|
|
feature cmd-feat1
|
|
feature cmd-feat2
|
|
event EVT_BOXED Object
|
|
boxed=True
|
|
feature feat3
|
|
doc freeform
|
|
body=
|
|
= Section
|
|
doc freeform
|
|
body=
|
|
Just text, no heading.
|
|
doc freeform
|
|
body=
|
|
== Subsection
|
|
|
|
*with emphasis*
|
|
@var {in braces}
|
|
|
|
* List item one
|
|
* Two, multiple
|
|
lines
|
|
|
|
* Three
|
|
Still in list
|
|
|
|
Not in list
|
|
|
|
- Second list
|
|
Note: still in list
|
|
|
|
Note: not in list
|
|
|
|
1. Third list
|
|
is numbered
|
|
|
|
2. another item
|
|
|
|
Returns: the King
|
|
Since: the first age
|
|
Notes:
|
|
|
|
1. Lorem ipsum dolor sit amet
|
|
|
|
2. Ut enim ad minim veniam
|
|
|
|
Duis aute irure dolor
|
|
|
|
Example:
|
|
|
|
-> in
|
|
<- out
|
|
Examples:
|
|
- *verbatim*
|
|
- {braces}
|
|
doc symbol=Enum
|
|
body=
|
|
|
|
arg=one
|
|
The _one_ {and only}, description on the same line
|
|
arg=two
|
|
|
|
feature=enum-feat
|
|
Also _one_ {and only}
|
|
feature=enum-member-feat
|
|
a member feature
|
|
section=Plain
|
|
@two is undocumented
|
|
doc symbol=Base
|
|
body=
|
|
|
|
arg=base1
|
|
description starts on a new line,
|
|
minimally indented
|
|
doc symbol=Variant1
|
|
body=
|
|
A paragraph
|
|
|
|
Another paragraph
|
|
|
|
@var1 is undocumented
|
|
arg=var1
|
|
|
|
feature=variant1-feat
|
|
a feature
|
|
feature=member-feat
|
|
a member feature
|
|
doc symbol=Variant2
|
|
body=
|
|
|
|
doc symbol=Object
|
|
body=
|
|
|
|
feature=union-feat1
|
|
a feature
|
|
doc symbol=Alternate
|
|
body=
|
|
|
|
arg=i
|
|
description starts on the same line
|
|
remainder indented the same
|
|
@b is undocumented
|
|
arg=b
|
|
|
|
feature=alt-feat
|
|
a feature
|
|
doc freeform
|
|
body=
|
|
== Another subsection
|
|
doc symbol=cmd
|
|
body=
|
|
|
|
arg=arg1
|
|
description starts on a new line,
|
|
indented
|
|
arg=arg2
|
|
description starts on the same line
|
|
remainder indented differently
|
|
arg=arg3
|
|
|
|
feature=cmd-feat1
|
|
a feature
|
|
feature=cmd-feat2
|
|
another feature
|
|
section=Plain
|
|
.. note:: @arg3 is undocumented
|
|
section=Returns
|
|
@Object
|
|
section=Errors
|
|
some
|
|
section=Todo
|
|
frobnicate
|
|
section=Plain
|
|
.. admonition:: Notes
|
|
|
|
- Lorem ipsum dolor sit amet
|
|
- Ut enim ad minim veniam
|
|
|
|
Duis aute irure dolor
|
|
|
|
.. qmp-example::
|
|
:title: Ideal fast-food burger situation
|
|
|
|
-> "in"
|
|
<- "out"
|
|
|
|
Examples::
|
|
|
|
- Not a QMP code block
|
|
- Merely a preformatted code block literal
|
|
It isn't even an rST list.
|
|
- *verbatim*
|
|
- {braces}
|
|
|
|
Note::
|
|
Ceci n'est pas une note
|
|
section=Since
|
|
2.10
|
|
doc symbol=cmd-boxed
|
|
body=
|
|
If you're bored enough to read this, go see a video of boxed cats
|
|
feature=cmd-feat1
|
|
a feature
|
|
feature=cmd-feat2
|
|
another feature
|
|
section=Plain
|
|
.. qmp-example::
|
|
|
|
-> "this example"
|
|
|
|
<- "has no title"
|
|
doc symbol=EVT_BOXED
|
|
body=
|
|
|
|
feature=feat3
|
|
a feature
|