mirror of
https://github.com/Motorhead1991/qemu.git
synced 2026-02-03 14:50:40 -07:00
63a97cf5a0
doc-good.json tests doc comment parser corner cases. We're about to largely replace it by a Sphinx extension, which will have different corner cases. Tweak the test so it passes both with the old parser and the Sphinx extension, by making it match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * the rules on when and where indentation matters differ * the '|' example syntax is going to go away entirely, so stop testing it This will avoid the tests spuriously breaking when we tighten up the parser code in the following commits. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-4-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com>
188 lines
3 KiB
Python
188 lines
3 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': { 'doc-required': true } }
|
|
|
|
##
|
|
# = Section
|
|
#
|
|
# == Subsection
|
|
#
|
|
# *strong* _with emphasis_
|
|
# @var {in braces}
|
|
#
|
|
# * List item one
|
|
# * Two, multiple
|
|
# lines
|
|
#
|
|
# * Three
|
|
# Still in list
|
|
#
|
|
# Not in list
|
|
#
|
|
# - Second list
|
|
# Note: still in list
|
|
#
|
|
# Note: not in list
|
|
#
|
|
# 1. Third list
|
|
# is numbered
|
|
#
|
|
# 2. another item
|
|
#
|
|
# Returns: the King
|
|
# Since: the first age
|
|
# Notes:
|
|
#
|
|
# 1. Lorem ipsum dolor sit amet
|
|
#
|
|
# 2. Ut enim ad minim veniam
|
|
#
|
|
# Duis aute irure dolor
|
|
#
|
|
# Example:
|
|
#
|
|
# -> in
|
|
# <- out
|
|
# Examples:
|
|
# - *verbatim*
|
|
# - {braces}
|
|
##
|
|
|
|
##
|
|
# @Enum:
|
|
# @one: The _one_ {and only}
|
|
#
|
|
# Features:
|
|
# @enum-feat: Also _one_ {and only}
|
|
#
|
|
# @two is undocumented
|
|
##
|
|
{ 'enum': 'Enum', 'data':
|
|
[ { 'name': 'one', 'if': 'defined(IFONE)' }, 'two' ],
|
|
'features': [ 'enum-feat' ],
|
|
'if': 'defined(IFCOND)' }
|
|
|
|
##
|
|
# @Base:
|
|
# @base1:
|
|
# the first member
|
|
##
|
|
{ 'struct': 'Base', 'data': { 'base1': 'Enum' } }
|
|
|
|
##
|
|
# @Variant1:
|
|
# A paragraph
|
|
#
|
|
# Another paragraph (but no @var: line)
|
|
#
|
|
# Features:
|
|
# @variant1-feat: a feature
|
|
# @member-feat: a member feature
|
|
##
|
|
{ 'struct': 'Variant1',
|
|
'features': [ 'variant1-feat' ],
|
|
'data': { 'var1': { 'type': 'str',
|
|
'features': [ 'member-feat' ],
|
|
'if': 'defined(IFSTR)' } } }
|
|
|
|
##
|
|
# @Variant2:
|
|
##
|
|
{ 'struct': 'Variant2', 'data': {} }
|
|
|
|
##
|
|
# @Object:
|
|
# Features:
|
|
# @union-feat1: a feature
|
|
##
|
|
{ 'union': 'Object',
|
|
'features': [ 'union-feat1' ],
|
|
'base': 'Base',
|
|
'discriminator': 'base1',
|
|
'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
|
|
|
|
##
|
|
# @SugaredUnion:
|
|
# Features:
|
|
# @union-feat2: a feature
|
|
##
|
|
{ 'union': 'SugaredUnion',
|
|
'features': [ 'union-feat2' ],
|
|
'data': { 'one': 'Variant1', 'two': { 'type': 'Variant2', 'if': 'IFTWO' } } }
|
|
|
|
##
|
|
# @Alternate:
|
|
# @i: an integer
|
|
# @b is undocumented
|
|
#
|
|
# Features:
|
|
# @alt-feat: a feature
|
|
##
|
|
{ 'alternate': 'Alternate',
|
|
'features': [ 'alt-feat' ],
|
|
'data': { 'i': 'int', 'b': 'bool' } }
|
|
|
|
##
|
|
# == Another subsection
|
|
##
|
|
|
|
##
|
|
# @cmd:
|
|
# @arg1: the first argument
|
|
#
|
|
# @arg2: the second
|
|
# argument
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
# Note: @arg3 is undocumented
|
|
# Returns: @Object
|
|
# TODO: frobnicate
|
|
# Notes:
|
|
#
|
|
# - Lorem ipsum dolor sit amet
|
|
# - Ut enim ad minim veniam
|
|
#
|
|
# Duis aute irure dolor
|
|
# Example:
|
|
#
|
|
# -> in
|
|
# <- out
|
|
# Examples:
|
|
# - *verbatim*
|
|
# - {braces}
|
|
# Since: 2.10
|
|
##
|
|
{ 'command': 'cmd',
|
|
'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
|
|
'returns': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @cmd-boxed:
|
|
# If you're bored enough to read this, go see a video of boxed cats
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
# Example:
|
|
#
|
|
# -> in
|
|
#
|
|
# <- out
|
|
##
|
|
{ 'command': 'cmd-boxed', 'boxed': true,
|
|
'data': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @EVT-BOXED:
|
|
# Features:
|
|
# @feat3: a feature
|
|
##
|
|
{ 'event': 'EVT-BOXED', 'boxed': true,
|
|
'features': [ 'feat3' ],
|
|
'data': 'Object' }
|