diff options
| author | Markus Armbruster <armbru@redhat.com> | 2024-06-28 13:27:56 +0200 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2024-07-06 08:58:24 +0200 |
| commit | e389929d19a543ea5b34d02553b355f9f1c03162 (patch) | |
| tree | 96e50b2eb03d6fcfe07518a525d63d895ec6bc3a /qapi | |
| parent | 65fa48c79f20a37c7204f9e43dd7cc3058aa066c (diff) | |
sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
When a command's arguments are specified as an explicit type T,
generated documentation points to the members of T.
Example:
##
# @announce-self:
#
# Trigger generation of broadcast RARP frames to update network
[...]
##
{ 'command': 'announce-self', 'boxed': true,
'data' : 'AnnounceParameters'}
generates
"announce-self" (Command)
-------------------------
Trigger generation of broadcast RARP frames to update network
[...]
Arguments
~~~~~~~~~
The members of "AnnounceParameters"
Except when the command takes its arguments unboxed , i.e. it doesn't
have 'boxed': true, we generate *nothing*. A few commands have a
reference in their doc comment to compensate, but most don't.
Example:
##
# @blockdev-snapshot-sync:
#
# Takes a synchronous snapshot of a block device.
#
# For the arguments, see the documentation of BlockdevSnapshotSync.
[...]
##
{ 'command': 'blockdev-snapshot-sync',
'data': 'BlockdevSnapshotSync',
'allow-preconfig': true }
generates
"blockdev-snapshot-sync" (Command)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Takes a synchronous snapshot of a block device.
For the arguments, see the documentation of BlockdevSnapshotSync.
[...]
Same for event data.
Fix qapidoc.py to generate the reference regardless of boxing. Delete
now redundant references in the doc comments.
Fixes: 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension)
Cc: qemu-stable@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240628112756.794237-1-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Diffstat (limited to 'qapi')
| -rw-r--r-- | qapi/block-core.json | 7 |
1 files changed, 0 insertions, 7 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json index 9ef23ec02a..096bdbe0aa 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1675,8 +1675,6 @@ # # Takes a synchronous snapshot of a block device. # -# For the arguments, see the documentation of BlockdevSnapshotSync. -# # Errors: # - If @device is not a valid block device, DeviceNotFound # @@ -1705,8 +1703,6 @@ # device, the block device changes to using 'overlay' as its new # active image. # -# For the arguments, see the documentation of BlockdevSnapshot. -# # Features: # # @allow-write-only-overlay: If present, the check whether this @@ -6065,9 +6061,6 @@ # string, or a snapshot with name already exists, the operation will # fail. # -# For the arguments, see the documentation of -# BlockdevSnapshotInternal. -# # Errors: # - If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty, |