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