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