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