diff mbox series

[v2,27/30] qapi: Use rST markup for literal blocks

Message ID 20200213175647.17628-28-peter.maydell@linaro.org
State Superseded
Headers show
Series Convert QAPI doc comments to generate rST instead of texinfo | expand

Commit Message

Peter Maydell Feb. 13, 2020, 5:56 p.m. UTC 
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.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---
 qapi/block-core.json  | 16 +++++++++-------
 qapi/qapi-schema.json |  6 ++++--
 2 files changed, 13 insertions(+), 9 deletions(-)

-- 
2.20.1
diff mbox series

Patch

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 13dad62f441..ea0371c33fb 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -550,13 +550,15 @@ 
 #        For the example above, @bins may be something like [3, 1, 5, 2],
 #        and corresponding histogram looks like:
 #
-# |      5|           *
-# |      4|           *
-# |      3| *         *
-# |      2| *         *    *
-# |      1| *    *    *    *
-# |       +------------------
-# |           10   50   100
+# ::
+#
+#        5|           *
+#        4|           *
+#        3| *         *
+#        2| *         *    *
+#        1| *    *    *    *
+#         +------------------
+#             10   50   100
 #
 # Since: 4.0
 ##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index f7ba60a5d0b..1d3fb573846 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -22,8 +22,10 @@ 
 #
 # 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
 # detailed information on the Server command and response formats.