tests/qapi-schema/doc-good.json

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