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# .. qmp-example::
176#    :title: Ideal fast-food burger situation
177#
178#    -> "in"
179#    <- "out"
180#
181# Examples::
182#
183#  - Not a QMP code block
184#  - Merely a preformatted code block literal
185#  It isn't even an rST list.
186#  - *verbatim*
187#  - {braces}
188#
189# Note::
190#     Ceci n'est pas une note
191#
192# Since: 2.10
193##
194{ 'command': 'cmd',
195  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
196  'returns': 'Object',
197  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
198
199##
200# @cmd-boxed:
201# If you're bored enough to read this, go see a video of boxed cats
202#
203# Features:
204# @cmd-feat1: a feature
205# @cmd-feat2: another feature
206#
207# .. qmp-example::
208#
209#    -> "this example"
210#
211#    <- "has no title"
212##
213{ 'command': 'cmd-boxed', 'boxed': true,
214  'data': 'Object',
215  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
216
217##
218# @EVT_BOXED:
219#
220# Features:
221# @feat3: a feature
222##
223{ 'event': 'EVT_BOXED',  'boxed': true,
224  'features': [ 'feat3' ],
225  'data': 'Object' }
226