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#
57# @one: The _one_ {and only}, description on the same line
58#
59# Features:
60# @enum-feat: Also _one_ {and only}
61# @enum-member-feat: a member feature
62#
63# @two is undocumented
64##
65{ 'enum': 'Enum',
66  'data': [ { 'name': 'one', 'if': 'IFONE',
67              'features': [ 'enum-member-feat' ] },
68            'two' ],
69  'features': [ 'enum-feat' ],
70  'if': 'IFCOND' }
71
72##
73# @Base:
74#
75# @base1:
76# description starts on a new line,
77# not indented
78##
79{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
80  'if': { 'all': ['IFALL1', 'IFALL2'] } }
81
82##
83# @Variant1:
84#
85# A paragraph
86#
87# Another paragraph
88#
89# @var1 is undocumented
90#
91# Features:
92# @variant1-feat: a feature
93# @member-feat: a member feature
94##
95{ 'struct': 'Variant1',
96  'features': [ 'variant1-feat' ],
97  'data': { 'var1': { 'type': 'str',
98                      'features': [ 'member-feat' ],
99                      'if': 'IFSTR' } } }
100
101##
102# @Variant2:
103#
104##
105{ 'struct': 'Variant2', 'data': {} }
106
107##
108# @Object:
109#
110# Features:
111# @union-feat1: a feature
112##
113{ 'union': 'Object',
114  'features': [ 'union-feat1' ],
115  'base': 'Base',
116  'discriminator': 'base1',
117  'data': { 'one': 'Variant1',
118            'two': { 'type': 'Variant2',
119                     'if': { 'any': ['IFONE', 'IFTWO'] } } } }
120
121##
122# @Alternate:
123#
124# @i: description starts on the same line
125#     remainder indented the same
126#     @b is undocumented
127#
128# Features:
129# @alt-feat: a feature
130##
131{ 'alternate': 'Alternate',
132  'features': [ 'alt-feat' ],
133  'data': { 'i': 'int', 'b': 'bool' },
134  'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
135
136##
137# == Another subsection
138##
139
140##
141# @cmd:
142#
143# @arg1:
144#     description starts on a new line,
145#     indented
146#
147# @arg2: description starts on the same line
148#     remainder indented differently
149#
150# Features:
151# @cmd-feat1: a feature
152# @cmd-feat2: another feature
153# Note: @arg3 is undocumented
154# Returns: @Object
155# TODO: frobnicate
156# Notes:
157#
158# - Lorem ipsum dolor sit amet
159# - Ut enim ad minim veniam
160#
161# Duis aute irure dolor
162# Example:
163#
164# -> in
165# <- out
166# Examples:
167# - *verbatim*
168# - {braces}
169# Since: 2.10
170##
171{ 'command': 'cmd',
172  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
173  'returns': 'Object',
174  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
175
176##
177# @cmd-boxed:
178# If you're bored enough to read this, go see a video of boxed cats
179# Features:
180# @cmd-feat1: a feature
181# @cmd-feat2: another feature
182# Example:
183#
184# -> in
185#
186# <- out
187##
188{ 'command': 'cmd-boxed', 'boxed': true,
189  'data': 'Object',
190  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
191
192##
193# @EVT_BOXED:
194#
195# Features:
196# @feat3: a feature
197##
198{ 'event': 'EVT_BOXED',  'boxed': true,
199  'features': [ 'feat3' ],
200  'data': 'Object' }
201