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 # == Produces *invalid* texinfo
  55 # @one: The _one_ {and only}
  56 #
  57 # @two is undocumented
  58 ##
  59 { 'enum': 'Enum', 'data': [ 'one', 'two' ] }
  60
  61 ##
  62 # @Base:
  63 # @base1:
  64 #   the first member
  65 ##
  66 { 'struct': 'Base', 'data': { 'base1': 'Enum' } }
  67
  68 ##
  69 # @Variant1:
  70 # A paragraph
  71 #
  72 # Another paragraph (but no @var: line)
  73 ##
  74 { 'struct': 'Variant1', 'data': { 'var1': 'str' } }
  75
  76 ##
  77 # @Variant2:
  78 ##
  79 { 'struct': 'Variant2', 'data': {} }
  80
  81 ##
  82 # @Object:
  83 ##
  84 { 'union': 'Object',
  85   'base': 'Base',
  86   'discriminator': 'base1',
  87   'data': { 'one': 'Variant1', 'two': 'Variant2' } }
  88
  89 ##
  90 # @SugaredUnion:
  91 ##
  92 { 'union': 'SugaredUnion',
  93   'data': { 'one': 'Variant1', 'two': 'Variant2' } }
  94
  95 ##
  96 # == Another subsection
  97 ##
  98
  99 ##
 100 # @cmd:
 101 # @arg1: the first argument
 102 #
 103 # @arg2: the second
 104 # argument
 105 # Note: @arg3 is undocumented
 106 # Returns: @Object
 107 # TODO: frobnicate
 108 # Notes:
 109 # - Lorem ipsum dolor sit amet
 110 # - Ut enim ad minim veniam
 111 #
 112 # Duis aute irure dolor
 113 # Example:
 114 #
 115 # -> in
 116 # <- out
 117 # Examples:
 118 # - *verbatim*
 119 # - {braces}
 120 # Since: 2.10
 121 ##
 122 { 'command': 'cmd',
 123   'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
 124   'returns': 'Object' }
 125
 126 ##
 127 # @cmd-boxed:
 128 # If you're bored enough to read this, go see a video of boxed cats
 129 # Example:
 130 #
 131 # -> in
 132 #
 133 # <- out
 134 ##
 135 { 'command': 'cmd-boxed', 'boxed': true,
 136   'data': 'Object' }