mirror of
https://github.com/mborgerson/xemu.git
synced 2026-03-15 16:35:20 +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>
234 lines
3.7 KiB
Python
234 lines
3.7 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': {
|
|
'doc-required': true,
|
|
'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
|
|
|
|
##
|
|
# *******
|
|
# Section
|
|
# *******
|
|
##
|
|
|
|
##
|
|
# Just text, no heading.
|
|
##
|
|
|
|
##
|
|
# 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}
|
|
##
|
|
|
|
# Not a doc comment
|
|
|
|
##
|
|
# @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
|
|
##
|
|
{ 'enum': 'Enum',
|
|
'data': [ { 'name': 'one', 'if': 'IFONE',
|
|
'features': [ 'enum-member-feat' ] },
|
|
'two' ],
|
|
'features': [ 'enum-feat' ],
|
|
'if': 'IFCOND' }
|
|
|
|
##
|
|
# @Base:
|
|
#
|
|
# @base1:
|
|
# description starts on a new line,
|
|
# minimally indented
|
|
##
|
|
{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
|
|
'if': { 'all': ['IFALL1', 'IFALL2'] } }
|
|
|
|
##
|
|
# @Variant1:
|
|
#
|
|
# A paragraph
|
|
#
|
|
# Another paragraph
|
|
#
|
|
# @var1 is undocumented
|
|
#
|
|
# Features:
|
|
# @variant1-feat: a feature
|
|
# @member-feat: a member feature
|
|
##
|
|
{ 'struct': 'Variant1',
|
|
'features': [ 'variant1-feat' ],
|
|
'data': { 'var1': { 'type': 'str',
|
|
'features': [ 'member-feat' ],
|
|
'if': 'IFSTR' } } }
|
|
|
|
##
|
|
# @Variant2:
|
|
#
|
|
##
|
|
{ 'struct': 'Variant2', 'data': {} }
|
|
|
|
##
|
|
# @Object:
|
|
#
|
|
# Features:
|
|
# @union-feat1: a feature
|
|
##
|
|
{ 'union': 'Object',
|
|
'features': [ 'union-feat1' ],
|
|
'base': 'Base',
|
|
'discriminator': 'base1',
|
|
'data': { 'one': 'Variant1',
|
|
'two': { 'type': 'Variant2',
|
|
'if': { 'any': ['IFONE', 'IFTWO'] } } } }
|
|
|
|
##
|
|
# @Alternate:
|
|
#
|
|
# @i: description starts on the same line
|
|
# remainder indented the same
|
|
# @b is undocumented
|
|
#
|
|
# Features:
|
|
# @alt-feat: a feature
|
|
##
|
|
{ 'alternate': 'Alternate',
|
|
'features': [ 'alt-feat' ],
|
|
'data': { 'i': 'int', 'b': 'bool' },
|
|
'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
|
|
|
|
##
|
|
# Another subsection
|
|
# ==================
|
|
##
|
|
|
|
##
|
|
# @cmd:
|
|
#
|
|
# @arg1:
|
|
# description starts on a new line,
|
|
# indented
|
|
#
|
|
# @arg2: description starts on the same line
|
|
# remainder indented differently
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
#
|
|
# .. note:: @arg3 is undocumented
|
|
#
|
|
# Returns: @Object
|
|
#
|
|
# Errors: some
|
|
#
|
|
# TODO: frobnicate
|
|
#
|
|
# .. 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
|
|
#
|
|
# Since: 2.10
|
|
##
|
|
{ 'command': 'cmd',
|
|
'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
|
|
'returns': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @cmd-boxed:
|
|
# If you're bored enough to read this, go see a video of boxed cats
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> "this example"
|
|
#
|
|
# <- ... has no title ...
|
|
##
|
|
{ 'command': 'cmd-boxed', 'boxed': true,
|
|
'data': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @EVT_BOXED:
|
|
#
|
|
# Features:
|
|
# @feat3: a feature
|
|
##
|
|
{ 'event': 'EVT_BOXED', 'boxed': true,
|
|
'features': [ 'feat3' ],
|
|
'data': 'Object' }
|