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

[Eric Blake]

On Tue, Apr 04, 2023 at 01:59:12PM +0200, 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

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>
> ---
>  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(-)

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org