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# *strong* _with emphasis_
14# @var {in braces}
15# * List item one
16# - Two, multiple
17#   lines
18#
19# 3. Three
20# Still in list
21#
22#   Not in list
23# - Second list
24# Note: still in list
25#
26# Note: not in list
27# 1. Third list
28#    is numbered
29#
30# - another item
31#
32# | example
33# | multiple lines
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# @one: The _one_ {and only}
57#
58# Features:
59# @enum-feat: Also _one_ {and only}
60#
61# @two is undocumented
62##
63{ 'enum': 'Enum', 'data':
64  [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],
65  'features': [ 'enum-feat' ],
66  'if': 'defined(IFCOND)' }
67
68##
69# @Base:
70# @base1:
71#   the first member
72##
73{ 'struct': 'Base', 'data': { 'base1': 'Enum' } }
74
75##
76# @Variant1:
77# A paragraph
78#
79# Another paragraph (but no @var: line)
80#
81# Features:
82# @variant1-feat: a feature
83# @member-feat: a member feature
84##
85{ 'struct': 'Variant1',
86  'features': [ 'variant1-feat' ],
87  'data': { 'var1': { 'type': 'str',
88                      'features': [ 'member-feat' ],
89                      'if': 'defined(IFSTR)' } } }
90
91##
92# @Variant2:
93##
94{ 'struct': 'Variant2', 'data': {} }
95
96##
97# @Object:
98# Features:
99# @union-feat1: a feature
100##
101{ 'union': 'Object',
102  'features': [ 'union-feat1' ],
103  'base': 'Base',
104  'discriminator': 'base1',
105  'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
106
107##
108# @SugaredUnion:
109# Features:
110# @union-feat2: a feature
111##
112{ 'union': 'SugaredUnion',
113  'features': [ 'union-feat2' ],
114  'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
115
116##
117# @Alternate:
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
128##
129# == Another subsection
130##
131
132##
133# @cmd:
134# @arg1: the first argument
135#
136# @arg2: the second
137# argument
138#
139# Features:
140# @cmd-feat1: a feature
141# @cmd-feat2: another feature
142# Note: @arg3 is undocumented
143# Returns: @Object
144# TODO: frobnicate
145# Notes:
146# - Lorem ipsum dolor sit amet
147# - Ut enim ad minim veniam
148#
149# Duis aute irure dolor
150# Example:
151#
152# -> in
153# <- out
154# Examples:
155# - *verbatim*
156# - {braces}
157# Since: 2.10
158##
159{ 'command': 'cmd',
160  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
161  'returns': 'Object',
162  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
163
164##
165# @cmd-boxed:
166# If you're bored enough to read this, go see a video of boxed cats
167# Features:
168# @cmd-feat1: a feature
169# @cmd-feat2: another feature
170# Example:
171#
172# -> in
173#
174# <- out
175##
176{ 'command': 'cmd-boxed', 'boxed': true,
177  'data': 'Object',
178  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
179
180##
181# @EVT-BOXED:
182# Features:
183# @feat3: a feature
184##
185{ 'event': 'EVT-BOXED',  'boxed': true,
186  'features': [ 'feat3' ],
187  'data': 'Object' }
188