[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-commen
From: |
Peter Maydell |
Subject: |
[PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks |
Date: |
Thu, 6 Feb 2020 17:30:30 +0000 |
Our current QAPI doc-comment markup allows section headers
(introduced with a leading '=' or '==') anywhere in any documentation
comment. This works for texinfo because the texi generator simply
prints a texinfo heading directive at that point in the output
stream. For rST generation, since we're assembling a tree of
docutils nodes, this is awkward because a new section implies
starting a new section node at the top level of the tree and
generating text into there.
New section headings in the middle of the documentation of a command
or event would be pretty nonsensical, and in fact we only ever output
new headings using 'freeform' doc comment blocks whose only content
is the single line of the heading, with two exceptions, which are in
the introductory freeform-doc-block at the top of
qapi/qapi-schema.json.
Split that doc-comment up so that the heading lines are in their own
doc-comment. This will allow us to tighten the specification to
insist that heading lines are always standalone, rather than
requiring the rST document generator to look at every line in a doc
comment block and handle headings in odd places.
This change makes no difference to the generated texi.
Signed-off-by: Peter Maydell <address@hidden>
---
qapi/qapi-schema.json | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 9751b11f8f1..f7ba60a5d0b 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -1,7 +1,9 @@
# -*- Mode: Python -*-
##
# = Introduction
-#
+##
+
+##
# This document describes all commands currently supported by QMP.
#
# Most of the time their usage is exactly the same as in the user Monitor, this
@@ -25,9 +27,13 @@
#
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
# detailed information on the Server command and response formats.
-#
+##
+
+##
# = Stability Considerations
-#
+##
+
+##
# The current QMP command set (described in this file) may be useful for a
# number of use cases, however it's limited and several commands have bad
# defined semantics, specially with regard to command completion.
--
2.20.1
- [PATCH 18/29] qapi/migration.json: Replace _this_ with *this*, (continued)
- [PATCH 20/29] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/02/06
- [PATCH 21/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/02/06
- [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists, Peter Maydell, 2020/02/06
- [PATCH 16/29] qapi/{block, misc, tmp}.json: Use explicit bulleted lists, Peter Maydell, 2020/02/06
- [PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks,
Peter Maydell <=
[PATCH 09/29] qapi: Fix indent level on doc comments in json files, Peter Maydell, 2020/02/06
[PATCH 27/29] qga/qapi-schema.json: Add some headings, Peter Maydell, 2020/02/06
[PATCH 22/29] scripts/qapi/parser.py: improve doc comment indent handling, Peter Maydell, 2020/02/06
[PATCH 26/29] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/02/06
[PATCH 24/29] docs/interop: Convert qemu-ga-ref to rST, Peter Maydell, 2020/02/06