tests/qapi-schema/doc-good.json

   1 # -*- Mode: Python -*-
   2 # Positive QAPI doc comment tests
   3
   4 { 'pragma': { 'doc-required': true } }
   5
   6 ##
   7 # = Section
   8 #
   9 # == Subsection
  10 #
  11 # *strong* _with emphasis_
  12 # @var {in braces}
  13 # * List item one
  14 # - Two, multiple
  15 #   lines
  16 #
  17 # 3. Three
  18 # Still in list
  19 #
  20 #   Not in list
  21 # - Second list
  22 # Note: still in list
  23 #
  24 # Note: not in list
  25 # 1. Third list
  26 #    is numbered
  27 #
  28 # - another item
  29 #
  30 # | example
  31 # | multiple lines
  32 #
  33 # Returns: the King
  34 # Since: the first age
  35 # Notes:
  36 #
  37 # 1. Lorem ipsum dolor sit amet
  38 #
  39 # 2. Ut enim ad minim veniam
  40 #
  41 # Duis aute irure dolor
  42 #
  43 # Example:
  44 #
  45 # -> in
  46 # <- out
  47 # Examples:
  48 # - *verbatim*
  49 # - {braces}
  50 ##
  51
  52 ##
  53 # @Enum:
  54 # @one: The _one_ {and only}
  55 #
  56 # Features:
  57 # @enum-feat: Also _one_ {and only}
  58 #
  59 # @two is undocumented
  60 ##
  61 { 'enum': 'Enum', 'data':
  62   [ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],
  63   'features': [ 'enum-feat' ],
  64   'if': 'defined(IFCOND)' }
  65
  66 ##
  67 # @Base:
  68 # @base1:
  69 #   the first member
  70 ##
  71 { 'struct': 'Base', 'data': { 'base1': 'Enum' } }
  72
  73 ##
  74 # @Variant1:
  75 # A paragraph
  76 #
  77 # Another paragraph (but no @var: line)
  78 #
  79 # Features:
  80 # @variant1-feat: a feature
  81 # @member-feat: a member feature
  82 ##
  83 { 'struct': 'Variant1',
  84   'features': [ 'variant1-feat' ],
  85   'data': { 'var1': { 'type': 'str',
  86                       'features': [ 'member-feat' ],
  87                       'if': 'defined(IFSTR)' } } }
  88
  89 ##
  90 # @Variant2:
  91 ##
  92 { 'struct': 'Variant2', 'data': {} }
  93
  94 ##
  95 # @Object:
  96 # Features:
  97 # @union-feat1: a feature
  98 ##
  99 { 'union': 'Object',
 100   'features': [ 'union-feat1' ],
 101   'base': 'Base',
 102   'discriminator': 'base1',
 103   'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
 104
 105 ##
 106 # @SugaredUnion:
 107 # Features:
 108 # @union-feat2: a feature
 109 ##
 110 { 'union': 'SugaredUnion',
 111   'features': [ 'union-feat2' ],
 112   'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
 113
 114 ##
 115 # @Alternate:
 116 # @i: an integer
 117 # @b is undocumented
 118 #
 119 # Features:
 120 # @alt-feat: a feature
 121 ##
 122 { 'alternate': 'Alternate',
 123   'features': [ 'alt-feat' ],
 124   'data': { 'i': 'int', 'b': 'bool' } }
 125
 126 ##
 127 # == Another subsection
 128 ##
 129
 130 ##
 131 # @cmd:
 132 # @arg1: the first argument
 133 #
 134 # @arg2: the second
 135 # argument
 136 #
 137 # Features:
 138 # @cmd-feat1: a feature
 139 # @cmd-feat2: another feature
 140 # Note: @arg3 is undocumented
 141 # Returns: @Object
 142 # TODO: frobnicate
 143 # Notes:
 144 # - Lorem ipsum dolor sit amet
 145 # - Ut enim ad minim veniam
 146 #
 147 # Duis aute irure dolor
 148 # Example:
 149 #
 150 # -> in
 151 # <- out
 152 # Examples:
 153 # - *verbatim*
 154 # - {braces}
 155 # Since: 2.10
 156 ##
 157 { 'command': 'cmd',
 158   'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
 159   'returns': 'Object',
 160   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
 161
 162 ##
 163 # @cmd-boxed:
 164 # If you're bored enough to read this, go see a video of boxed cats
 165 # Features:
 166 # @cmd-feat1: a feature
 167 # @cmd-feat2: another feature
 168 # Example:
 169 #
 170 # -> in
 171 #
 172 # <- out
 173 ##
 174 { 'command': 'cmd-boxed', 'boxed': true,
 175   'data': 'Object',
 176   'features': [ 'cmd-feat1', 'cmd-feat2' ] }
 177
 178 ##
 179 # @EVT-BOXED:
 180 # Features:
 181 # @feat3: a feature
 182 ##
 183 { 'event': 'EVT-BOXED',  'boxed': true,
 184   'features': [ 'feat3' ],
 185   'data': 'Object' }