[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 16/17] qapi storage-daemon/qapi: Fix documentation section structu
From: |
Markus Armbruster |
Subject: |
[PULL 16/17] qapi storage-daemon/qapi: Fix documentation section structure |
Date: |
Fri, 28 Apr 2023 12:29:00 +0200 |
In the QEMU QMP Reference Manual, subsection "Block core (VM
unrelated)" is empty. Its contents is at the end of subsection
"Background jobs" instead. That's because qapi/job.json is included
first from qapi/block-core.json, which makes qapi/job.json's
documentation go between qapi/block-core.json's subsection heading and
contents.
In the QEMU Storage Daemon QMP Reference Manual, section "Block
Devices" contains nothing but an empty subsection "Block core (VM
unrelated)". The latter's contents is at the end section "Socket data
types", along with subsection "Block device exports". Subsection
"Background jobs" is at the end of section "Cryptography". All this
is because storage-daemon/qapi/qapi-schema.json includes modules in a
confused order.
Fix both as follows.
Turn subsection "Background jobs" into a section.
Move it before section "Block devices" in the QEMU QMP Reference
Manual, by including qapi/jobs.json right before qapi/block.json.
Reorder include directives in storage-daemon/qapi/qapi-schema.json to
match the order in qapi/qapi-schema.json, so that the QEMU Storage
Daemon QMP Reference Manual's section structure the QEMU QMP Reference
Manual's.
In the QEMU QMP Reference Manual, qapi/cryptodev.json's documentation
is at the end of section "Virtio devices". That's because it lacks a
section heading, and therefore gets squashed into whatever section
happens to precede it.
Add section heading so it's in section "Cryptography devices".
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Acked-by: zhenwei pi <pizhenwei@bytedance.com>
Message-Id: <20230425064223.820979-17-armbru@redhat.com>
---
qapi/cryptodev.json | 4 ++++
qapi/job.json | 2 +-
qapi/qapi-schema.json | 2 +-
storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++-------
4 files changed, 21 insertions(+), 9 deletions(-)
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index f33f96a692..cf960ea81f 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -4,6 +4,10 @@
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.
+##
+# = Cryptography devices
+##
+
##
# @QCryptodevBackendAlgType:
#
diff --git a/qapi/job.json b/qapi/job.json
index bc4104757a..9e29a796c5 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -2,7 +2,7 @@
# vim: filetype=python
##
-# == Background jobs
+# = Background jobs
##
##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index e57d8ff801..bb7217da26 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -43,11 +43,11 @@
{ 'include': 'sockets.json' }
{ 'include': 'run-state.json' }
{ 'include': 'crypto.json' }
+{ 'include': 'job.json' }
{ 'include': 'block.json' }
{ 'include': 'block-export.json' }
{ 'include': 'char.json' }
{ 'include': 'dump.json' }
-{ 'include': 'job.json' }
{ 'include': 'net.json' }
{ 'include': 'rdma.json' }
{ 'include': 'rocker.json' }
diff --git a/storage-daemon/qapi/qapi-schema.json
b/storage-daemon/qapi/qapi-schema.json
index 67749d1101..f10c949490 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -15,18 +15,26 @@
{ 'include': '../../qapi/pragma.json' }
+# Documentation generated with qapi-gen.py is in source order, with
+# included sub-schemas inserted at the first include directive
+# (subsequent include directives have no effect). To get a sane and
+# stable order, it's best to include each sub-schema just once, or
+# include it first right here.
+
+{ 'include': '../../qapi/common.json' }
+{ 'include': '../../qapi/sockets.json' }
+{ 'include': '../../qapi/crypto.json' }
+{ 'include': '../../qapi/job.json' }
+
##
# = Block devices
##
{ 'include': '../../qapi/block-core.json' }
{ 'include': '../../qapi/block-export.json' }
+
{ 'include': '../../qapi/char.json' }
-{ 'include': '../../qapi/common.json' }
-{ 'include': '../../qapi/control.json' }
-{ 'include': '../../qapi/crypto.json' }
-{ 'include': '../../qapi/introspect.json' }
-{ 'include': '../../qapi/job.json' }
{ 'include': '../../qapi/authz.json' }
-{ 'include': '../../qapi/qom.json' }
-{ 'include': '../../qapi/sockets.json' }
{ 'include': '../../qapi/transaction.json' }
+{ 'include': '../../qapi/control.json' }
+{ 'include': '../../qapi/introspect.json' }
+{ 'include': '../../qapi/qom.json' }
--
2.39.2
- [PULL 00/17] QAPI patches patches for 2023-04-28, Markus Armbruster, 2023/04/28
- [PULL 04/17] qapi: Fix up references to long gone error classes, Markus Armbruster, 2023/04/28
- [PULL 12/17] qapi: Fix argument documentation markup, Markus Armbruster, 2023/04/28
- [PULL 06/17] qapi: @foo should be used to reference, not ``foo``, Markus Armbruster, 2023/04/28
- [PULL 09/17] qapi: Fix bullet list markup in documentation, Markus Armbruster, 2023/04/28
- [PULL 03/17] qapi: Fix misspelled references, Markus Armbruster, 2023/04/28
- [PULL 01/17] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status, Markus Armbruster, 2023/04/28
- [PULL 15/17] qapi: Format since information the conventional way: (since X.Y), Markus Armbruster, 2023/04/28
- [PULL 05/17] qapi/block-core: Clean up after removal of dirty bitmap @status, Markus Armbruster, 2023/04/28
- [PULL 13/17] qapi: Replace ad hoc "since" documentation by member documentation, Markus Armbruster, 2023/04/28
- [PULL 16/17] qapi storage-daemon/qapi: Fix documentation section structure,
Markus Armbruster <=
- [PULL 08/17] qapi: Delete largely misleading "Stability Considerations", Markus Armbruster, 2023/04/28
- [PULL 14/17] qapi: Fix misspelled section tags in doc comments, Markus Armbruster, 2023/04/28
- [PULL 07/17] qapi: Tidy up examples, Markus Armbruster, 2023/04/28
- [PULL 02/17] qga/qapi-schema: Fix a misspelled reference, Markus Armbruster, 2023/04/28
- [PULL 11/17] qga/qapi-schema: Fix member documentation markup, Markus Armbruster, 2023/04/28
- [PULL 17/17] docs/devel/qapi-code-gen: Describe some doc markup pitfalls, Markus Armbruster, 2023/04/28
- [PULL 10/17] qapi: Fix unintended definition lists in documentation, Markus Armbruster, 2023/04/28
- Re: [PULL 00/17] QAPI patches patches for 2023-04-28, Richard Henderson, 2023/04/29