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