b09c8f7a99
doc-good.json currently uses the old *strong* and _emphasis_ markup.
As part of the conversion to rST this needs to switch to **strong**
and *emphasis*, because rST uses underscores as part of its markup
of hyperlinks and will otherwise warn about the syntax error.
In commit a660eed482 we fixed up the in-tree uses of the
old markup:
1) _this_ was replaced with *this*
2) the only in-tree use of *this* was left alone (turning
a 'strong' into an 'emphasis')
(and so currently in-tree nothing is using either new-style
**strong** or old-style _emphasis_).
Update doc-good.json in a similar way:
1) replace _this_ with *this*
2) remove the usage of old-style *this*
(This slightly reduces the coverage for the old Texinfo generator,
which is about to go away, but is fine for the new rST generator
because that does not need to handle strong/emphasis itself because
it is simply passing the entire text as raw rST to Sphinx.)
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-13-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
189 lines
3 KiB
Python
189 lines
3 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': { 'doc-required': true } }
|
|
|
|
##
|
|
# = Section
|
|
#
|
|
# == Subsection
|
|
#
|
|
# *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' }
|