2017-03-20 14:11:54 +01:00
|
|
|
# -*- Mode: Python -*-
|
2020-07-29 20:50:24 +02:00
|
|
|
# vim: filetype=python
|
|
|
|
#
|
2017-03-20 14:11:54 +01:00
|
|
|
# Positive QAPI doc comment tests
|
|
|
|
|
|
|
|
{ 'pragma': { 'doc-required': true } }
|
|
|
|
|
|
|
|
##
|
|
|
|
# = Section
|
|
|
|
#
|
|
|
|
# == Subsection
|
|
|
|
#
|
2020-09-25 18:23:07 +02:00
|
|
|
# *with emphasis*
|
2017-03-20 14:11:54 +01:00
|
|
|
# @var {in braces}
|
2020-09-25 18:22:58 +02:00
|
|
|
#
|
2017-03-20 14:11:54 +01:00
|
|
|
# * List item one
|
2020-09-25 18:22:58 +02:00
|
|
|
# * Two, multiple
|
2017-03-20 14:11:54 +01:00
|
|
|
# lines
|
|
|
|
#
|
2020-09-25 18:22:58 +02:00
|
|
|
# * Three
|
|
|
|
# Still in list
|
|
|
|
#
|
|
|
|
# Not in list
|
2017-03-20 14:11:54 +01:00
|
|
|
#
|
|
|
|
# - Second list
|
2020-09-25 18:22:58 +02:00
|
|
|
# Note: still in list
|
2017-03-20 14:11:54 +01:00
|
|
|
#
|
|
|
|
# Note: not in list
|
2020-09-25 18:22:58 +02:00
|
|
|
#
|
2017-03-20 14:11:54 +01:00
|
|
|
# 1. Third list
|
|
|
|
# is numbered
|
|
|
|
#
|
2020-09-25 18:22:58 +02:00
|
|
|
# 2. another item
|
2017-03-20 14:11:54 +01:00
|
|
|
#
|
|
|
|
# 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}
|
|
|
|
#
|
2020-03-17 12:54:37 +01:00
|
|
|
# Features:
|
|
|
|
# @enum-feat: Also _one_ {and only}
|
|
|
|
#
|
2017-03-20 14:11:54 +01:00
|
|
|
# @two is undocumented
|
|
|
|
##
|
2018-12-13 13:37:20 +01:00
|
|
|
{ 'enum': 'Enum', 'data':
|
|
|
|
[ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],
|
2020-03-17 12:54:37 +01:00
|
|
|
'features': [ 'enum-feat' ],
|
2018-12-13 13:37:20 +01:00
|
|
|
'if': 'defined(IFCOND)' }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
|
|
|
##
|
|
|
|
# @Base:
|
|
|
|
# @base1:
|
2020-09-25 18:22:58 +02:00
|
|
|
# the first member
|
2017-03-20 14:11:54 +01:00
|
|
|
##
|
2021-08-04 10:31:01 +02:00
|
|
|
{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
|
|
|
|
'if': { 'all': ['IFALL1', 'IFALL2'] } }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
|
|
|
##
|
|
|
|
# @Variant1:
|
|
|
|
# A paragraph
|
|
|
|
#
|
|
|
|
# Another paragraph (but no @var: line)
|
2019-10-18 10:14:53 +02:00
|
|
|
#
|
|
|
|
# Features:
|
|
|
|
# @variant1-feat: a feature
|
2020-03-17 12:54:45 +01:00
|
|
|
# @member-feat: a member feature
|
2017-03-20 14:11:54 +01:00
|
|
|
##
|
2018-12-13 13:37:21 +01:00
|
|
|
{ 'struct': 'Variant1',
|
2019-10-18 10:14:53 +02:00
|
|
|
'features': [ 'variant1-feat' ],
|
2020-03-17 12:54:45 +01:00
|
|
|
'data': { 'var1': { 'type': 'str',
|
|
|
|
'features': [ 'member-feat' ],
|
|
|
|
'if': 'defined(IFSTR)' } } }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
|
|
|
##
|
|
|
|
# @Variant2:
|
|
|
|
##
|
|
|
|
{ 'struct': 'Variant2', 'data': {} }
|
|
|
|
|
|
|
|
##
|
|
|
|
# @Object:
|
2020-03-17 12:54:37 +01:00
|
|
|
# Features:
|
|
|
|
# @union-feat1: a feature
|
2017-03-20 14:11:54 +01:00
|
|
|
##
|
|
|
|
{ 'union': 'Object',
|
2020-03-17 12:54:37 +01:00
|
|
|
'features': [ 'union-feat1' ],
|
2017-03-20 14:11:54 +01:00
|
|
|
'base': 'Base',
|
|
|
|
'discriminator': 'base1',
|
2018-12-13 13:37:22 +01:00
|
|
|
'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
|
|
|
##
|
|
|
|
# @SugaredUnion:
|
2020-03-17 12:54:37 +01:00
|
|
|
# Features:
|
|
|
|
# @union-feat2: a feature
|
2017-03-20 14:11:54 +01:00
|
|
|
##
|
|
|
|
{ 'union': 'SugaredUnion',
|
2020-03-17 12:54:37 +01:00
|
|
|
'features': [ 'union-feat2' ],
|
2018-12-13 13:37:22 +01:00
|
|
|
'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
2019-10-24 13:02:21 +02:00
|
|
|
##
|
|
|
|
# @Alternate:
|
|
|
|
# @i: an integer
|
2020-09-25 18:22:58 +02:00
|
|
|
# @b is undocumented
|
2020-03-17 12:54:37 +01:00
|
|
|
#
|
|
|
|
# Features:
|
|
|
|
# @alt-feat: a feature
|
2019-10-24 13:02:21 +02:00
|
|
|
##
|
|
|
|
{ 'alternate': 'Alternate',
|
2020-03-17 12:54:37 +01:00
|
|
|
'features': [ 'alt-feat' ],
|
2019-10-24 13:02:21 +02:00
|
|
|
'data': { 'i': 'int', 'b': 'bool' } }
|
|
|
|
|
2017-03-20 14:11:54 +01:00
|
|
|
##
|
|
|
|
# == Another subsection
|
|
|
|
##
|
|
|
|
|
|
|
|
##
|
|
|
|
# @cmd:
|
|
|
|
# @arg1: the first argument
|
|
|
|
#
|
|
|
|
# @arg2: the second
|
2020-09-25 18:22:58 +02:00
|
|
|
# argument
|
2019-10-18 10:14:53 +02:00
|
|
|
#
|
|
|
|
# Features:
|
|
|
|
# @cmd-feat1: a feature
|
|
|
|
# @cmd-feat2: another feature
|
2017-03-20 14:11:54 +01:00
|
|
|
# Note: @arg3 is undocumented
|
|
|
|
# Returns: @Object
|
|
|
|
# TODO: frobnicate
|
|
|
|
# Notes:
|
2020-09-25 18:22:58 +02:00
|
|
|
#
|
2017-03-20 14:11:54 +01:00
|
|
|
# - 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' },
|
2019-10-18 10:14:53 +02:00
|
|
|
'returns': 'Object',
|
|
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
2017-03-20 14:11:54 +01:00
|
|
|
|
|
|
|
##
|
|
|
|
# @cmd-boxed:
|
|
|
|
# If you're bored enough to read this, go see a video of boxed cats
|
2019-10-18 10:14:53 +02:00
|
|
|
# Features:
|
|
|
|
# @cmd-feat1: a feature
|
|
|
|
# @cmd-feat2: another feature
|
2017-03-20 14:11:54 +01:00
|
|
|
# Example:
|
|
|
|
#
|
|
|
|
# -> in
|
|
|
|
#
|
|
|
|
# <- out
|
|
|
|
##
|
|
|
|
{ 'command': 'cmd-boxed', 'boxed': true,
|
2019-10-18 10:14:53 +02:00
|
|
|
'data': 'Object',
|
|
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
2019-10-24 13:02:20 +02:00
|
|
|
|
|
|
|
##
|
2021-03-23 10:40:10 +01:00
|
|
|
# @EVT_BOXED:
|
2020-03-17 12:54:37 +01:00
|
|
|
# Features:
|
|
|
|
# @feat3: a feature
|
2019-10-24 13:02:20 +02:00
|
|
|
##
|
2021-03-23 10:40:10 +01:00
|
|
|
{ 'event': 'EVT_BOXED', 'boxed': true,
|
2020-03-17 12:54:37 +01:00
|
|
|
'features': [ 'feat3' ],
|
2019-10-24 13:02:20 +02:00
|
|
|
'data': 'Object' }
|