1# -*- Mode: Python -*-
2# Positive QAPI doc comment tests
3
4{ 'pragma': { 'doc-required': true } }
5
6##
7# = Section
8#
9# == Subsection
10#
11# *strong* _with emphasis_
12# @var {in braces}
13# * List item one
14# - Two, multiple
15#   lines
16#
17# 3. Three
18# Still in list
19#
20#   Not in list
21# - Second list
22# Note: still in list
23#
24# Note: not in list
25# 1. Third list
26#    is numbered
27#
28# - another item
29#
30# | example
31# | multiple lines
32#
33# Returns: the King
34# Since: the first age
35# Notes:
36#
37# 1. Lorem ipsum dolor sit amet
38#
39# 2. Ut enim ad minim veniam
40#
41# Duis aute irure dolor
42#
43# Example:
44#
45# -> in
46# <- out
47# Examples:
48# - *verbatim*
49# - {braces}
50##
51
52##
53# @Enum:
54# @one: The _one_ {and only}
55#
56# @two is undocumented
57##
58{ 'enum': 'Enum', 'data':
59  [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],
60  'if': 'defined(IFCOND)' }
61
62##
63# @Base:
64# @base1:
65#   the first member
66##
67{ 'struct': 'Base', 'data': { 'base1': 'Enum' } }
68
69##
70# @Variant1:
71# A paragraph
72#
73# Another paragraph (but no @var: line)
74#
75# Features:
76# @variant1-feat: a feature
77##
78{ 'struct': 'Variant1',
79  'features': [ 'variant1-feat' ],
80  'data': { 'var1': { 'type': 'str', 'if': 'defined(IFSTR)' } } }
81
82##
83# @Variant2:
84##
85{ 'struct': 'Variant2', 'data': {} }
86
87##
88# @Object:
89##
90{ 'union': 'Object',
91  'base': 'Base',
92  'discriminator': 'base1',
93  'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
94
95##
96# @SugaredUnion:
97##
98{ 'union': 'SugaredUnion',
99  'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
100
101##
102# @Alternate:
103# @i: an integer
104# @b is undocumented
105##
106{ 'alternate': 'Alternate',
107  'data': { 'i': 'int', 'b': 'bool' } }
108
109##
110# == Another subsection
111##
112
113##
114# @cmd:
115# @arg1: the first argument
116#
117# @arg2: the second
118# argument
119#
120# Features:
121# @cmd-feat1: a feature
122# @cmd-feat2: another feature
123# Note: @arg3 is undocumented
124# Returns: @Object
125# TODO: frobnicate
126# Notes:
127# - Lorem ipsum dolor sit amet
128# - Ut enim ad minim veniam
129#
130# Duis aute irure dolor
131# Example:
132#
133# -> in
134# <- out
135# Examples:
136# - *verbatim*
137# - {braces}
138# Since: 2.10
139##
140{ 'command': 'cmd',
141  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
142  'returns': 'Object',
143  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
144
145##
146# @cmd-boxed:
147# If you're bored enough to read this, go see a video of boxed cats
148# Features:
149# @cmd-feat1: a feature
150# @cmd-feat2: another feature
151# Example:
152#
153# -> in
154#
155# <- out
156##
157{ 'command': 'cmd-boxed', 'boxed': true,
158  'data': 'Object',
159  'features': [ 'cmd-feat1', 'cmd-feat2' ] }
160
161##
162# @EVT-BOXED:
163##
164{ 'event': 'EVT-BOXED',  'boxed': true,
165  'data': 'Object' }
166