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