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