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