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