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