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# TODO: frobnicate 163# 164# Notes: 165# 166# - Lorem ipsum dolor sit amet 167# - Ut enim ad minim veniam 168# 169# Duis aute irure dolor 170# 171# Example: 172# 173# -> in 174# <- out 175# 176# Examples: 177# - *verbatim* 178# - {braces} 179# 180# Since: 2.10 181## 182{ 'command': 'cmd', 183 'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' }, 184 'returns': 'Object', 185 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 186 187## 188# @cmd-boxed: 189# If you're bored enough to read this, go see a video of boxed cats 190# 191# Features: 192# @cmd-feat1: a feature 193# @cmd-feat2: another feature 194# 195# Example: 196# 197# -> in 198# 199# <- out 200## 201{ 'command': 'cmd-boxed', 'boxed': true, 202 'data': 'Object', 203 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 204 205## 206# @EVT_BOXED: 207# 208# Features: 209# @feat3: a feature 210## 211{ 'event': 'EVT_BOXED', 'boxed': true, 212 'features': [ 'feat3' ], 213 'data': 'Object' } 214