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# *strong* _with emphasis_ 14# @var {in braces} 15# * List item one 16# - Two, multiple 17# lines 18# 19# 3. Three 20# Still in list 21# 22# Not in list 23# - Second list 24# Note: still in list 25# 26# Note: not in list 27# 1. Third list 28# is numbered 29# 30# - another item 31# 32# | example 33# | multiple lines 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# @one: The _one_ {and only} 57# 58# Features: 59# @enum-feat: Also _one_ {and only} 60# 61# @two is undocumented 62## 63{ 'enum': 'Enum', 'data': 64 [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ], 65 'features': [ 'enum-feat' ], 66 'if': 'defined(IFCOND)' } 67 68## 69# @Base: 70# @base1: 71# the first member 72## 73{ 'struct': 'Base', 'data': { 'base1': 'Enum' } } 74 75## 76# @Variant1: 77# A paragraph 78# 79# Another paragraph (but no @var: line) 80# 81# Features: 82# @variant1-feat: a feature 83# @member-feat: a member feature 84## 85{ 'struct': 'Variant1', 86 'features': [ 'variant1-feat' ], 87 'data': { 'var1': { 'type': 'str', 88 'features': [ 'member-feat' ], 89 'if': 'defined(IFSTR)' } } } 90 91## 92# @Variant2: 93## 94{ 'struct': 'Variant2', 'data': {} } 95 96## 97# @Object: 98# Features: 99# @union-feat1: a feature 100## 101{ 'union': 'Object', 102 'features': [ 'union-feat1' ], 103 'base': 'Base', 104 'discriminator': 'base1', 105 'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } } 106 107## 108# @SugaredUnion: 109# Features: 110# @union-feat2: a feature 111## 112{ 'union': 'SugaredUnion', 113 'features': [ 'union-feat2' ], 114 'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } } 115 116## 117# @Alternate: 118# @i: an integer 119# @b is undocumented 120# 121# Features: 122# @alt-feat: a feature 123## 124{ 'alternate': 'Alternate', 125 'features': [ 'alt-feat' ], 126 'data': { 'i': 'int', 'b': 'bool' } } 127 128## 129# == Another subsection 130## 131 132## 133# @cmd: 134# @arg1: the first argument 135# 136# @arg2: the second 137# argument 138# 139# Features: 140# @cmd-feat1: a feature 141# @cmd-feat2: another feature 142# Note: @arg3 is undocumented 143# Returns: @Object 144# TODO: frobnicate 145# Notes: 146# - Lorem ipsum dolor sit amet 147# - Ut enim ad minim veniam 148# 149# Duis aute irure dolor 150# Example: 151# 152# -> in 153# <- out 154# Examples: 155# - *verbatim* 156# - {braces} 157# Since: 2.10 158## 159{ 'command': 'cmd', 160 'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' }, 161 'returns': 'Object', 162 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 163 164## 165# @cmd-boxed: 166# If you're bored enough to read this, go see a video of boxed cats 167# Features: 168# @cmd-feat1: a feature 169# @cmd-feat2: another feature 170# Example: 171# 172# -> in 173# 174# <- out 175## 176{ 'command': 'cmd-boxed', 'boxed': true, 177 'data': 'Object', 178 'features': [ 'cmd-feat1', 'cmd-feat2' ] } 179 180## 181# @EVT-BOXED: 182# Features: 183# @feat3: a feature 184## 185{ 'event': 'EVT-BOXED', 'boxed': true, 186 'features': [ 'feat3' ], 187 'data': 'Object' } 188