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