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