qapi storage-daemon/qapi: Fix documentation section structure

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>

diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index f33f96a69203995c4bf48c611e39ead4049b77b4..cf960ea81fd3421617a7819cf436303308ea4453 100644 (file)
--- 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 bc4104757afe185ab45ff24d2c2c3df56a5db31c..9e29a796c53059dc683e407f4a3b13c520dca2ba 100644 (file)
--- 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 e57d8ff8016cb505049fa349197b34bdd5b47e55..bb7217da26eab4ab5064302f71ec98b5e01e9fab 100644 (file)
--- 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 67749d11013686b14344a8e409e2e34a4191340c..f10c94949068c9e1e2e069ae8734c034b3fad940 100644 (file)
--- 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/authz.json' }
+{ 'include': '../../qapi/transaction.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' }