b6c18755e4
This is quite similar to commit 84ab008687 "qapi: Add feature flags to
struct members", only for enums instead of structs.
Special feature flag 'deprecated' is silently ignored there. This is
okay only because it will be implemented shortly.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20211025042405.3762351-3-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
195 lines
3.0 KiB
Python
195 lines
3.0 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': { 'doc-required': true } }
|
|
|
|
##
|
|
# = Section
|
|
#
|
|
# == 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}
|
|
##
|
|
|
|
##
|
|
# @Enum:
|
|
#
|
|
# @one: The _one_ {and only}
|
|
#
|
|
# 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:
|
|
# the first member
|
|
##
|
|
{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
|
|
'if': { 'all': ['IFALL1', 'IFALL2'] } }
|
|
|
|
##
|
|
# @Variant1:
|
|
#
|
|
# A paragraph
|
|
#
|
|
# Another paragraph (but no @var: line)
|
|
#
|
|
# 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: an integer
|
|
# @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: the first argument
|
|
#
|
|
# @arg2: the second
|
|
# argument
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
# Note: @arg3 is undocumented
|
|
# Returns: @Object
|
|
# TODO: frobnicate
|
|
# Notes:
|
|
#
|
|
# - Lorem ipsum dolor sit amet
|
|
# - Ut enim ad minim veniam
|
|
#
|
|
# Duis aute irure dolor
|
|
# Example:
|
|
#
|
|
# -> in
|
|
# <- out
|
|
# Examples:
|
|
# - *verbatim*
|
|
# - {braces}
|
|
# 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
|
|
# Example:
|
|
#
|
|
# -> in
|
|
#
|
|
# <- out
|
|
##
|
|
{ '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' }
|