[PULL 15/18] qapi: Add missing union tag documentation

[Markus Armbruster <armbru@redhat.com>]

Low-hanging fruit, and except for StatsFilter, the only members of
these unions lacking documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-16-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
 qapi/block-core.json   | 12 ++++++++++++
 qapi/block-export.json |  2 ++
 qapi/char.json         |  2 ++
 qapi/crypto.json       |  2 ++
 qapi/machine.json      |  4 ++++
 qapi/migration.json    |  2 ++
 qapi/pragma.json       | 16 ----------------
 qapi/sockets.json      |  2 ++
 qapi/stats.json        |  2 ++
 qapi/transaction.json  |  2 ++
 qapi/ui.json           |  2 ++
 qapi/yank.json         |  2 ++
 12 files changed, 34 insertions(+), 16 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 55b583f079..ded6437c06 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -252,6 +252,8 @@
 # A discriminated record of image format specific information
 # structures.
 #
+# @type: block driver name
+#
 # Since: 1.7
 ##
 { 'union': 'ImageInfoSpecific',
@@ -1102,6 +1104,8 @@
 #
 # Block driver specific statistics
 #
+# @driver: block driver name
+#
 # Since: 4.2
 ##
 { 'union': 'BlockStatsSpecific',
@@ -3472,6 +3476,8 @@
 ##
 # @BlockdevQcowEncryption:
 #
+# @format: encryption format
+#
 # Since: 2.10
 ##
 { 'union': 'BlockdevQcowEncryption',
@@ -3506,6 +3512,8 @@
 ##
 # @BlockdevQcow2Encryption:
 #
+# @format: encryption format
+#
 # Since: 2.10
 ##
 { 'union': 'BlockdevQcow2Encryption',
@@ -3656,6 +3664,8 @@
 ##
 # @SshHostKeyCheck:
 #
+# @mode: How to check the host key
+#
 # Since: 2.12
 ##
 { 'union': 'SshHostKeyCheck',
@@ -4225,6 +4235,8 @@
 ##
 # @RbdEncryptionCreateOptions:
 #
+# @format: Encryption format.
+#
 # Since: 6.1
 ##
 { 'union': 'RbdEncryptionCreateOptions',
diff --git a/qapi/block-export.json b/qapi/block-export.json
index e063e9255a..d9bd376b48 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -346,6 +346,8 @@
 # Describes a block export, i.e. how single node should be exported on
 # an external interface.
 #
+# @type: Block export type
+#
 # @id: A unique identifier for the block export (across all export
 #     types)
 #
diff --git a/qapi/char.json b/qapi/char.json
index e3e1b2c9f5..390e3ef1b9 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -634,6 +634,8 @@
 #
 # Configuration info for the new chardev backend.
 #
+# @type: backend type
+#
 # Since: 1.4
 ##
 { 'union': 'ChardevBackend',
diff --git a/qapi/crypto.json b/qapi/crypto.json
index fd3d46ebd1..03de66e6f6 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -645,6 +645,8 @@
 # The options that are available for all asymmetric key algorithms
 # when creating a new QCryptoAkCipher.
 #
+# @alg: encryption cipher algorithm
+#
 # Since: 7.1
 ##
 { 'union': 'QCryptoAkCipherOptions',
diff --git a/qapi/machine.json b/qapi/machine.json
index 6a25e39f44..d816c5c02e 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -443,6 +443,8 @@
 #
 # A discriminated record of NUMA options.  (for OptsVisitor)
 #
+# @type: NUMA option type
+#
 # Since: 2.1
 ##
 { 'union': 'NumaOptions',
@@ -1448,6 +1450,8 @@
 #
 # Union containing information about a memory device
 #
+# @type: memory device type
+#
 # Since: 2.1
 ##
 { 'union': 'MemoryDeviceInfo',
diff --git a/qapi/migration.json b/qapi/migration.json
index bf89765a26..7c8881abda 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1630,6 +1630,8 @@
 #
 # Migration endpoint configuration.
 #
+# @transport: The migration stream transport mechanism
+#
 # Since: 8.2
 ##
 { 'union': 'MigrationAddress',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index d5e3f6f142..7ac05ccc26 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -39,18 +39,13 @@
         'BlockDirtyBitmapAddWrapper',
         'BlockDirtyBitmapMergeWrapper',
         'BlockDirtyBitmapWrapper',
-        'BlockExportOptions',
-        'BlockStatsSpecific',
         'BlockdevBackupWrapper',
         'BlockdevDriver',
-        'BlockdevQcow2Encryption',
         'BlockdevQcow2EncryptionFormat',
-        'BlockdevQcowEncryption',
         'BlockdevSnapshotInternalWrapper',
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'ChardevBackend',
         'ChardevBackendKind',
         'CpuS390Entitlement',
         'CpuS390Polarization',
@@ -64,7 +59,6 @@
         'GrabToggleKeys',
         'GuestPanicInformationHyperV',
         'HotKeyMod',
-        'ImageInfoSpecific',
         'ImageInfoSpecificKind',
         'InputAxis',
         'InputButton',
@@ -73,38 +67,28 @@
         'IscsiHeaderDigest',
         'IscsiTransport',
         'JSONType',
-        'KeyValue',
         'KeyValueKind',
-        'MemoryDeviceInfo',
         'MemoryDeviceInfoKind',
         'MigrateSetParameters',
-        'MigrationAddress',
         'NetClientDriver',
-        'NumaOptions',
         'ObjectType',
         'PciMemoryRegion',
         'QCryptoAkCipherKeyType',
-        'QCryptoAkCipherOptions',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'Qcow2OverlapCheckFlags',
         'RbdAuthMode',
-        'RbdEncryptionCreateOptions',
         'RbdImageEncryptionFormat',
-        'SocketAddressLegacy',
-        'SshHostKeyCheck',
         'StatsFilter',
         'StatsValue',
         'String',
         'StringWrapper',
         'SysEmuTarget',
         'ThrottleGroupProperties',
-        'TransactionAction',
         'VncPrimaryAuth',
         'VncVencryptSubAuth',
         'X86CPURegister32',
         'XDbgBlockGraph',
-        'YankInstance',
         'YankInstanceType',
         'blockdev-reopen',
         'query-cpu-model-baseline',
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 5e6af5504d..ef777928e7 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -178,6 +178,8 @@
 # Captures the address of a socket, which could also be a named file
 # descriptor
 #
+# @type: Transport type
+#
 # Note: This type is deprecated in favor of SocketAddress.  The
 #     difference between SocketAddressLegacy and SocketAddress is that
 #     the latter has fewer {} on the wire.
diff --git a/qapi/stats.json b/qapi/stats.json
index 01791e86d5..ce9d8161ec 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -120,6 +120,8 @@
 # - which providers to request statistics from
 # - which named values to return within each provider
 #
+# @target: the kind of objects to query
+#
 # Since: 7.1
 ##
 { 'union': 'StatsFilter',
diff --git a/qapi/transaction.json b/qapi/transaction.json
index cffee2de28..7a95c081e9 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -158,6 +158,8 @@
 # A discriminated record of operations that can be performed with
 # @transaction.
 #
+# @type: the operation to be performed
+#
 # Since: 1.1
 ##
 { 'union': 'TransactionAction',
diff --git a/qapi/ui.json b/qapi/ui.json
index 1eccad0a83..b6d7e142b7 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1012,6 +1012,8 @@
 #
 # Represents a keyboard key.
 #
+# @type: key encoding
+#
 # Since: 1.3
 ##
 { 'union': 'KeyValue',
diff --git a/qapi/yank.json b/qapi/yank.json
index bfc71a07a6..ee038a11a1 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -49,6 +49,8 @@
 # A yank instance can be yanked with the @yank qmp command to recover
 # from a hanging QEMU.
 #
+# @type: yank instance type
+#
 # Currently implemented yank instances:
 #
 # - nbd block device: Yanking it will shut down the connection to the
-- 
2.43.0