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': [ 'one', 'two' ] }
59
60##
61# @Base:
62# @base1:
63#   the first member
64##
65{ 'struct': 'Base', 'data': { 'base1': 'Enum' } }
66
67##
68# @Variant1:
69# A paragraph
70#
71# Another paragraph (but no @var: line)
72##
73{ 'struct': 'Variant1', 'data': { 'var1': 'str' } }
74
75##
76# @Variant2:
77##
78{ 'struct': 'Variant2', 'data': {} }
79
80##
81# @Object:
82##
83{ 'union': 'Object',
84  'base': 'Base',
85  'discriminator': 'base1',
86  'data': { 'one': 'Variant1', 'two': 'Variant2' } }
87
88##
89# @SugaredUnion:
90##
91{ 'union': 'SugaredUnion',
92  'data': { 'one': 'Variant1', 'two': 'Variant2' } }
93
94##
95# == Another subsection
96##
97
98##
99# @cmd:
100# @arg1: the first argument
101#
102# @arg2: the second
103# argument
104# Note: @arg3 is undocumented
105# Returns: @Object
106# TODO: frobnicate
107# Notes:
108# - Lorem ipsum dolor sit amet
109# - Ut enim ad minim veniam
110#
111# Duis aute irure dolor
112# Example:
113#
114# -> in
115# <- out
116# Examples:
117# - *verbatim*
118# - {braces}
119# Since: 2.10
120##
121{ 'command': 'cmd',
122  'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
123  'returns': 'Object' }
124
125##
126# @cmd-boxed:
127# If you're bored enough to read this, go see a video of boxed cats
128# Example:
129#
130# -> in
131#
132# <- out
133##
134{ 'command': 'cmd-boxed', 'boxed': true,
135  'data': 'Object' }
136