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