3a025d3d1f
We use section "Returns" for documenting both success and error response of commands. I intend to generate better command success response documentation. Easier when "Returns" documents just he success response. Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-4-armbru@redhat.com>
216 lines
3.3 KiB
Python
216 lines
3.3 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': {
|
|
'doc-required': true,
|
|
'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
|
|
|
|
##
|
|
# = 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}, 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
|
|
#
|
|
# 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' }
|