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