qapi: Use rST markup for literal blocks

There are exactly two places in our json doc comments where we
use the markup accepted by the texi doc generator where a '|' in
the first line of a doc comment means the line should be emitted
as a literal block (fixed-width font, whitespace preserved).

Since we use this syntax so rarely, instead of making the rST
generator support it, instead just convert the two uses to
rST-format literal blocks, which are indented and introduced
with '::'.

(The rST generator doesn't complain about the old style syntax,
it just emits it with the '|' and with the whitespace not
preserved, which looks odd, but means we can safely leave this
change until after we've stopped generating texinfo.)

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-11-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Peter Maydell 2020-09-25 17:23:05 +01:00 committed by Markus Armbruster
parent 4ac2ee194b
commit a0fcff383b
2 changed files with 13 additions and 9 deletions

View File

@ -570,13 +570,15 @@
# For the example above, @bins may be something like [3, 1, 5, 2], # For the example above, @bins may be something like [3, 1, 5, 2],
# and corresponding histogram looks like: # and corresponding histogram looks like:
# #
# | 5| * # ::
# | 4| * #
# | 3| * * # 5| *
# | 2| * * * # 4| *
# | 1| * * * * # 3| * *
# | +------------------ # 2| * * *
# | 10 50 100 # 1| * * * *
# +------------------
# 10 50 100
# #
# Since: 4.0 # Since: 4.0
## ##

View File

@ -21,8 +21,10 @@
# #
# Example: # Example:
# #
# | -> data issued by the Client # ::
# | <- Server data response #
# -> data issued by the Client
# <- Server data response
# #
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
# detailed information on the Server command and response formats. # detailed information on the Server command and response formats.