1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4# Positive QAPI doc comment tests 5 6{ 'pragma': { 7 'doc-required': true, 8 'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } } 9 10## 11# = Section 12## 13 14## 15# Just text, no heading. 16## 17 18## 19# == Subsection 20# 21# *with emphasis* 22# @var {in braces} 23# 24# * List item one 25# * Two, multiple 26# lines 27# 28# * Three 29# Still in list 30# 31# Not in list 32# 33# - Second list 34# Note: still in list 35# 36# Note: not in list 37# 38# 1. Third list 39# is numbered 40# 41# 2. another item 42# 43# Returns: the King 44# Since: the first age 45# Notes: 46# 47# 1. Lorem ipsum dolor sit amet 48# 49# 2. Ut enim ad minim veniam 50# 51# Duis aute irure dolor 52# 53# Example: 54# 55# -> in 56# <- out 57# Examples: 58# - *verbatim* 59# - {braces} 60## 61 62# Not a doc comment 63 64## 65# @Enum: 66# 67# @one: The _one_ {and only}, description on the same line 68# 69# Features: 70# @enum-feat: Also _one_ {and only} 71# @enum-member-feat: a member feature 72# 73# @two is undocumented 74## 75{ 'enum': 'Enum', 76 'data': [ { 'name': 'one', 'if': 'IFONE', 77 'features': [ 'enum-member-feat' ] }, 78 'two' ], 79 'features': [ 'enum-feat' ], 80 'if': 'IFCOND' } 81 82## 83# @Base: 84# 85# @base1: 86# description starts on a new line, 87# minimally indented 88## 89{ 'struct': 'Base', 'data': { 'base1': 'Enum' }, 90 'if': { 'all': ['IFALL1', 'IFALL2'] } } 91 92## 93# @Variant1: 94# 95# A paragraph 96# 97# Another paragraph 98# 99# @var1 is undocumented 100# 101# Features: 102# @variant1-feat: a feature 103# @member-feat: a member feature 104## 105{ 'struct': 'Variant1', 106 'features': [ 'variant1-feat' ], 107 'data': { 'var1': { 'type': 'str', 108 'features': [ 'member-feat' ], 109 'if': 'IFSTR' } } } 110 111## 112# @Variant2: 113# 114## 115{ 'struct': 'Variant2', 'data': {} } 116 117## 118# @Object: 119# 120# Features: 121# @union-feat1: a feature 122## 123{ 'union': 'Object', 124 'features': [ 'union-feat1' ], 125 'base': 'Base', 126 'discriminator': 'base1', 127 'data': { 'one': 'Variant1', 128 'two': { 'type': 'Variant2', 129 'if': { 'any': ['IFONE', 'IFTWO'] } } } } 130 131## 132# @Alternate: 133# 134# @i: description starts on the same line 135# remainder indented the same 136# @b is undocumented 137# 138# Features: 139# @alt-feat: a feature 140## 141{ 'alternate': 'Alternate', 142 'features': [ 'alt-feat' ], 143 'data': { 'i': 'int', 'b': 'bool' }, 144 'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } } 145 146## 147# == Another subsection 148## 149 150## 151# @cmd: 152# 153# @arg1: 154# description starts on a new line, 155# indented 156# 157# @arg2: description starts on the same line 158# remainder indented differently 159# 160# Features: 161# @cmd-feat1: a feature 162# @cmd-feat2: another feature 163# 164# .. note:: @arg3 is undocumented 165# 166# Returns: @Object 167# 168# Errors: some 169# 170# TODO: frobnicate 171# 172# .. admonition:: Notes 173# 174# - Lorem ipsum dolor sit amet 175# - Ut enim ad minim veniam 176# 177# Duis aute irure dolor 178# 179# .. qmp-example:: 180# :title: Ideal fast-food burger situation 181# 182# -> "in" 183# <- "out" 184# 185# Examples:: 186# 187# - Not a QMP code block 188# - Merely a preformatted code block literal 189# It isn't even an rST list. 190# - *verbatim* 191# - {braces} 192# 193# Note:: 194# Ceci n'est pas une note 195# 196# Since: 2.10 197## 198{ 'command': 'cmd', 199 'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' }, 200 'returns': 'Object', 201 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 202 203## 204# @cmd-boxed: 205# If you're bored enough to read this, go see a video of boxed cats 206# 207# Features: 208# @cmd-feat1: a feature 209# @cmd-feat2: another feature 210# 211# .. qmp-example:: 212# 213# -> "this example" 214# 215# <- ... has no title ... 216## 217{ 'command': 'cmd-boxed', 'boxed': true, 218 'data': 'Object', 219 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 220 221## 222# @EVT_BOXED: 223# 224# Features: 225# @feat3: a feature 226## 227{ 'event': 'EVT_BOXED', 'boxed': true, 228 'features': [ 'feat3' ], 229 'data': 'Object' } 230