mirror of
https://github.com/qemu/qemu.git
synced 2025-08-17 07:16:28 +00:00
6c10778826
Remove the QAPI doc section heading syntax, use plain rST section headings instead. Tests and documentation are updated to match. Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250618165353.1980365-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Add more detail to commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com>
230 lines
3.7 KiB
Plaintext
230 lines
3.7 KiB
Plaintext
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
|