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