Re: [PATCH 16/16] qapi storage-daemon/qapi: Fix documentation section structure

[zhenwei pi]

Looks good to me, thanks!

Acked-by: zhenwei pi <pizhenwei@bytedance.com>

On 4/4/23 19:59, Markus Armbruster wrote:
> 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 includeded
> 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>
> ---
>   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' }

--
zhenwei pi