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

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> 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

Fixing...

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

Thanks!