Merge remote-tracking branch 'remotes/jasowang/tags/net-pull-request' into staging
[qemu.git] / tests / qapi-schema / doc-good.json
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 # @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 #
147 # - Lorem ipsum dolor sit amet
148 # - Ut enim ad minim veniam
149 #
150 # Duis aute irure dolor
151 # Example:
152 #
153 # -> in
154 # <- out
155 # Examples:
156 # - *verbatim*
157 # - {braces}
158 # Since: 2.10
159 ##
160 { 'command': 'cmd',
161   'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
162   'returns': 'Object',
163   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
164
165 ##
166 # @cmd-boxed:
167 # If you're bored enough to read this, go see a video of boxed cats
168 # Features:
169 # @cmd-feat1: a feature
170 # @cmd-feat2: another feature
171 # Example:
172 #
173 # -> in
174 #
175 # <- out
176 ##
177 { 'command': 'cmd-boxed', 'boxed': true,
178   'data': 'Object',
179   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
180
181 ##
182 # @EVT_BOXED:
183 # Features:
184 # @feat3: a feature
185 ##
186 { 'event': 'EVT_BOXED',  'boxed': true,
187   'features': [ 'feat3' ],
188   'data': 'Object' }