tests/qapi-schema/doc-good.json

   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' }