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 ##
  59 # @Enum:
  60 #
  61 # @one: The _one_ {and only}, description on the same line
  62 #
  63 # Features:
  64 # @enum-feat: Also _one_ {and only}
  65 # @enum-member-feat: a member feature
  66 #
  67 # @two is undocumented
  68 ##
  69 { 'enum': 'Enum',
  70   'data': [ { 'name': 'one', 'if': 'IFONE',
  71               'features': [ 'enum-member-feat' ] },
  72             'two' ],
  73   'features': [ 'enum-feat' ],
  74   'if': 'IFCOND' }
  75
  76 ##
  77 # @Base:
  78 #
  79 # @base1:
  80 #  description starts on a new line,
  81 #  minimally indented
  82 ##
  83 { 'struct': 'Base', 'data': { 'base1': 'Enum' },
  84   'if': { 'all': ['IFALL1', 'IFALL2'] } }
  85
  86 ##
  87 # @Variant1:
  88 #
  89 # A paragraph
  90 #
  91 # Another paragraph
  92 #
  93 # @var1 is undocumented
  94 #
  95 # Features:
  96 # @variant1-feat: a feature
  97 # @member-feat: a member feature
  98 ##
  99 { 'struct': 'Variant1',
 100   'features': [ 'variant1-feat' ],
 101   'data': { 'var1': { 'type': 'str',
 102                       'features': [ 'member-feat' ],
 103                       'if': 'IFSTR' } } }
 104
 105 ##
 106 # @Variant2:
 107 #
 108 ##
 109 { 'struct': 'Variant2', 'data': {} }
 110
 111 ##
 112 # @Object:
 113 #
 114 # Features:
 115 # @union-feat1: a feature
 116 ##
 117 { 'union': 'Object',
 118   'features': [ 'union-feat1' ],
 119   'base': 'Base',
 120   'discriminator': 'base1',
 121   'data': { 'one': 'Variant1',
 122             'two': { 'type': 'Variant2',
 123                      'if': { 'any': ['IFONE', 'IFTWO'] } } } }
 124
 125 ##
 126 # @Alternate:
 127 #
 128 # @i: description starts on the same line
 129 #     remainder indented the same
 130 #     @b is undocumented
 131 #
 132 # Features:
 133 # @alt-feat: a feature
 134 ##
 135 { 'alternate': 'Alternate',
 136   'features': [ 'alt-feat' ],
 137   'data': { 'i': 'int', 'b': 'bool' },
 138   'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
 139
 140 ##
 141 # == Another subsection
 142 ##
 143
 144 ##
 145 # @cmd:
 146 #
 147 # @arg1:
 148 #     description starts on a new line,
 149 #     indented
 150 #
 151 # @arg2: description starts on the same line
 152 #     remainder indented differently
 153 #
 154 # Features:
 155 # @cmd-feat1: a feature
 156 # @cmd-feat2: another feature
 157 #
 158 # Note: @arg3 is undocumented
 159 #
 160 # Returns: @Object
 161 #
 162 # Errors: some
 163 #
 164 # TODO: frobnicate
 165 #
 166 # Notes:
 167 #
 168 #  - Lorem ipsum dolor sit amet
 169 #  - Ut enim ad minim veniam
 170 #
 171 #  Duis aute irure dolor
 172 #
 173 # Example:
 174 #
 175 #  -> in
 176 #  <- out
 177 #
 178 # Examples:
 179 #  - *verbatim*
 180 #  - {braces}
 181 #
 182 # Since: 2.10
 183 ##
 184 { 'command': 'cmd',
 185   'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
 186   'returns': 'Object',
 187   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
 188
 189 ##
 190 # @cmd-boxed:
 191 # If you're bored enough to read this, go see a video of boxed cats
 192 #
 193 # Features:
 194 # @cmd-feat1: a feature
 195 # @cmd-feat2: another feature
 196 #
 197 # Example:
 198 #
 199 #  -> in
 200 #
 201 #  <- out
 202 ##
 203 { 'command': 'cmd-boxed', 'boxed': true,
 204   'data': 'Object',
 205   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
 206
 207 ##
 208 # @EVT_BOXED:
 209 #
 210 # Features:
 211 # @feat3: a feature
 212 ##
 213 { 'event': 'EVT_BOXED',  'boxed': true,
 214   'features': [ 'feat3' ],
 215   'data': 'Object' }