1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4# Positive QAPI doc comment tests
5
6{ 'pragma': { 'doc-required': true } }
7
8##
9# = Section
10#
11# == Subsection
12#
13# *with emphasis*
14# @var {in braces}
15#
16# * List item one
17# * Two, multiple
18#   lines
19#
20# * Three
21#   Still in list
22#
23# Not in list
24#
25# - Second list
26#   Note: still in list
27#
28# Note: not in list
29#
30# 1. Third list
31#    is numbered
32#
33# 2. another item
34#
35# Returns: the King
36# Since: the first age
37# Notes:
38#
39# 1. Lorem ipsum dolor sit amet
40#
41# 2. Ut enim ad minim veniam
42#
43# Duis aute irure dolor
44#
45# Example:
46#
47# -> in
48# <- out
49# Examples:
50# - *verbatim*
51# - {braces}
52##
53
54##
55# @Enum:
56# @one: The _one_ {and only}
57#
58# Features:
59# @enum-feat: Also _one_ {and only}
60#
61# @two is undocumented
62##
63{ 'enum': 'Enum',
64  'data': [ { 'name': 'one', 'if': 'IFONE' }, 'two' ],
65  'features': [ 'enum-feat' ],
66  'if': 'IFCOND' }
67
68##
69# @Base:
70# @base1:
71# the first member
72##
73{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
74  'if': { 'all': ['IFALL1', 'IFALL2'] } }
75
76##
77# @Variant1:
78# A paragraph
79#
80# Another paragraph (but no @var: line)
81#
82# Features:
83# @variant1-feat: a feature
84# @member-feat: a member feature
85##
86{ 'struct': 'Variant1',
87  'features': [ 'variant1-feat' ],
88  'data': { 'var1': { 'type': 'str',
89                      'features': [ 'member-feat' ],
90                      'if': 'IFSTR' } } }
91
92##
93# @Variant2:
94##
95{ 'struct': 'Variant2', 'data': {} }
96
97##
98# @Object:
99# Features:
100# @union-feat1: a feature
101##
102{ 'union': 'Object',
103  'features': [ 'union-feat1' ],
104  'base': 'Base',
105  'discriminator': 'base1',
106  'data': { 'one': 'Variant1',
107            'two': { 'type': 'Variant2',
108                     'if': { 'any': ['IFONE', 'IFTWO'] } } } }
109
110##
111# @Alternate:
112# @i: an integer
113#     @b is undocumented
114#
115# Features:
116# @alt-feat: a feature
117##
118{ 'alternate': 'Alternate',
119  'features': [ 'alt-feat' ],
120  'data': { 'i': 'int', 'b': 'bool' },
121  'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
122
123##
124# == Another subsection
125##
126
127##
128# @cmd:
129# @arg1: the first argument
130#
131# @arg2: the second
132#        argument
133#
134# Features:
135# @cmd-feat1: a feature
136# @cmd-feat2: another feature
137# Note: @arg3 is undocumented
138# Returns: @Object
139# TODO: frobnicate
140# Notes:
141#
142# - Lorem ipsum dolor sit amet
143# - Ut enim ad minim veniam
144#
145# Duis aute irure dolor
146# Example:
147#
148# -> in
149# <- out
150# Examples:
151# - *verbatim*
152# - {braces}
153# Since: 2.10
154##
155{ 'command': 'cmd',
156  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
157  'returns': 'Object',
158  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
159
160##
161# @cmd-boxed:
162# If you're bored enough to read this, go see a video of boxed cats
163# Features:
164# @cmd-feat1: a feature
165# @cmd-feat2: another feature
166# Example:
167#
168# -> in
169#
170# <- out
171##
172{ 'command': 'cmd-boxed', 'boxed': true,
173  'data': 'Object',
174  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
175
176##
177# @EVT_BOXED:
178# Features:
179# @feat3: a feature
180##
181{ 'event': 'EVT_BOXED',  'boxed': true,
182  'features': [ 'feat3' ],
183  'data': 'Object' }
184