diff mbox series

[12/15] qapi: Plug trivial documentation holes around former simple unions

Message ID 20240205074709.3613229-13-armbru@redhat.com
State New
Headers show
Series qapi: Require member documentation (with loophole) | expand

Commit Message

Markus Armbruster Feb. 5, 2024, 7:47 a.m. UTC 
The conversion of simple to flat unions left the @data members
undocumented.  Add documentation where it's trivial.  Copy verbatim
from the wrapped type's description where possible.

Leftovers: String (to be taken care of in the next commit), and
TransActionAction (left for another day).

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/block-core.json | 10 ++++++++++
 qapi/char.json       | 26 ++++++++++++++++++++++++++
 qapi/machine.json    | 10 ++++++++++
 qapi/pragma.json     | 34 ----------------------------------
 qapi/sockets.json    |  6 ++++++
 qapi/tpm.json        |  4 ++++
 qapi/ui.json         | 12 ++++++++++++
 7 files changed, 68 insertions(+), 34 deletions(-)

Comments

Daniel P. Berrangé Feb. 7, 2024, 8:36 a.m. UTC | #1 
On Mon, Feb 05, 2024 at 08:47:06AM +0100, Markus Armbruster wrote:
> The conversion of simple to flat unions left the @data members
> undocumented.  Add documentation where it's trivial.  Copy verbatim
> from the wrapped type's description where possible.
> 
> Leftovers: String (to be taken care of in the next commit), and
> TransActionAction (left for another day).
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/block-core.json | 10 ++++++++++
>  qapi/char.json       | 26 ++++++++++++++++++++++++++
>  qapi/machine.json    | 10 ++++++++++
>  qapi/pragma.json     | 34 ----------------------------------
>  qapi/sockets.json    |  6 ++++++
>  qapi/tpm.json        |  4 ++++
>  qapi/ui.json         | 12 ++++++++++++
>  7 files changed, 68 insertions(+), 34 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
diff mbox series

Patch

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 80ed4122f2..55b583f079 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -196,6 +196,8 @@ 
 ##
 # @ImageInfoSpecificQCow2Wrapper:
 #
+# @data: image information specific to QCOW2
+#
 # Since: 1.7
 ##
 { 'struct': 'ImageInfoSpecificQCow2Wrapper',
@@ -204,6 +206,8 @@ 
 ##
 # @ImageInfoSpecificVmdkWrapper:
 #
+# @data: image information specific to VMDK
+#
 # Since: 6.1
 ##
 { 'struct': 'ImageInfoSpecificVmdkWrapper',
@@ -212,6 +216,8 @@ 
 ##
 # @ImageInfoSpecificLUKSWrapper:
 #
+# @data: image information specific to LUKS
+#
 # Since: 2.7
 ##
 { 'struct': 'ImageInfoSpecificLUKSWrapper',
@@ -223,6 +229,8 @@ 
 ##
 # @ImageInfoSpecificRbdWrapper:
 #
+# @data: image information specific to RBD
+#
 # Since: 6.1
 ##
 { 'struct': 'ImageInfoSpecificRbdWrapper',
@@ -231,6 +239,8 @@ 
 ##
 # @ImageInfoSpecificFileWrapper:
 #
+# @data: image information specific to files
+#
 # Since: 8.0
 ##
 { 'struct': 'ImageInfoSpecificFileWrapper',
diff --git a/qapi/char.json b/qapi/char.json
index 6c6ad3b10c..e3e1b2c9f5 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -498,6 +498,8 @@ 
 ##
 # @ChardevFileWrapper:
 #
+# @data: Configuration info for file chardevs
+#
 # Since: 1.4
 ##
 { 'struct': 'ChardevFileWrapper',
@@ -506,6 +508,8 @@ 
 ##
 # @ChardevHostdevWrapper:
 #
+# @data: Configuration info for device and pipe chardevs
+#
 # Since: 1.4
 ##
 { 'struct': 'ChardevHostdevWrapper',
@@ -514,6 +518,8 @@ 
 ##
 # @ChardevSocketWrapper:
 #
+# @data: Configuration info for (stream) socket chardevs
+#
 # Since: 1.4
 ##
 { 'struct': 'ChardevSocketWrapper',
@@ -522,6 +528,8 @@ 
 ##
 # @ChardevUdpWrapper:
 #
+# @data: Configuration info for datagram socket chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevUdpWrapper',
@@ -530,6 +538,8 @@ 
 ##
 # @ChardevCommonWrapper:
 #
+# @data: Configuration shared across all chardev backends
+#
 # Since: 2.6
 ##
 { 'struct': 'ChardevCommonWrapper',
@@ -538,6 +548,8 @@ 
 ##
 # @ChardevMuxWrapper:
 #
+# @data: Configuration info for mux chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevMuxWrapper',
@@ -546,6 +558,8 @@ 
 ##
 # @ChardevStdioWrapper:
 #
+# @data: Configuration info for stdio chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevStdioWrapper',
@@ -554,6 +568,8 @@ 
 ##
 # @ChardevSpiceChannelWrapper:
 #
+# @data: Configuration info for spice vm channel chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpiceChannelWrapper',
@@ -563,6 +579,8 @@ 
 ##
 # @ChardevSpicePortWrapper:
 #
+# @data: Configuration info for spice port chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevSpicePortWrapper',
@@ -572,6 +590,8 @@ 
 ##
 # @ChardevQemuVDAgentWrapper:
 #
+# @data: Configuration info for qemu vdagent implementation
+#
 # Since: 6.1
 ##
 { 'struct': 'ChardevQemuVDAgentWrapper',
@@ -581,6 +601,8 @@ 
 ##
 # @ChardevDBusWrapper:
 #
+# @data: Configuration info for DBus chardevs
+#
 # Since: 7.0
 ##
 { 'struct': 'ChardevDBusWrapper',
@@ -590,6 +612,8 @@ 
 ##
 # @ChardevVCWrapper:
 #
+# @data: Configuration info for virtual console chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevVCWrapper',
@@ -598,6 +622,8 @@ 
 ##
 # @ChardevRingbufWrapper:
 #
+# @data: Configuration info for ring buffer chardevs
+#
 # Since: 1.5
 ##
 { 'struct': 'ChardevRingbufWrapper',
diff --git a/qapi/machine.json b/qapi/machine.json
index aa99fa333f..6a25e39f44 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1396,6 +1396,8 @@ 
 ##
 # @PCDIMMDeviceInfoWrapper:
 #
+# @data: PCDIMMDevice state information
+#
 # Since: 2.1
 ##
 { 'struct': 'PCDIMMDeviceInfoWrapper',
@@ -1404,6 +1406,8 @@ 
 ##
 # @VirtioPMEMDeviceInfoWrapper:
 #
+# @data: VirtioPMEM state information
+#
 # Since: 2.1
 ##
 { 'struct': 'VirtioPMEMDeviceInfoWrapper',
@@ -1412,6 +1416,8 @@ 
 ##
 # @VirtioMEMDeviceInfoWrapper:
 #
+# @data: VirtioMEMDevice state information
+#
 # Since: 2.1
 ##
 { 'struct': 'VirtioMEMDeviceInfoWrapper',
@@ -1420,6 +1426,8 @@ 
 ##
 # @SgxEPCDeviceInfoWrapper:
 #
+# @data: Sgx EPC state information
+#
 # Since: 6.2
 ##
 { 'struct': 'SgxEPCDeviceInfoWrapper',
@@ -1428,6 +1436,8 @@ 
 ##
 # @HvBalloonDeviceInfoWrapper:
 #
+# @data: hv-balloon provided memory state information
+#
 # Since: 8.2
 ##
 { 'struct': 'HvBalloonDeviceInfoWrapper',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index aea6384255..d5e3f6f142 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -52,19 +52,6 @@ 
         'BlockdevVmdkAdapterType',
         'ChardevBackend',
         'ChardevBackendKind',
-        'ChardevCommonWrapper',
-        'ChardevDBusWrapper',
-        'ChardevFileWrapper',
-        'ChardevHostdevWrapper',
-        'ChardevMuxWrapper',
-        'ChardevQemuVDAgentWrapper',
-        'ChardevRingbufWrapper',
-        'ChardevSocketWrapper',
-        'ChardevSpiceChannelWrapper',
-        'ChardevSpicePortWrapper',
-        'ChardevStdioWrapper',
-        'ChardevUdpWrapper',
-        'ChardevVCWrapper',
         'CpuS390Entitlement',
         'CpuS390Polarization',
         'CpuS390State',
@@ -77,24 +64,12 @@ 
         'GrabToggleKeys',
         'GuestPanicInformationHyperV',
         'HotKeyMod',
-        'HvBalloonDeviceInfoWrapper',
         'ImageInfoSpecific',
-        'ImageInfoSpecificFileWrapper',
         'ImageInfoSpecificKind',
-        'ImageInfoSpecificLUKSWrapper',
-        'ImageInfoSpecificQCow2Wrapper',
-        'ImageInfoSpecificRbdWrapper',
-        'ImageInfoSpecificVmdkWrapper',
-        'InetSocketAddressWrapper',
         'InputAxis',
-        'InputBtnEventWrapper',
         'InputButton',
-        'InputKeyEventWrapper',
-        'InputMoveEventWrapper',
         'InputMultiTouchEvent',
-        'InputMultiTouchEventWrapper',
         'InputMultiTouchType',
-        'IntWrapper',
         'IscsiHeaderDigest',
         'IscsiTransport',
         'JSONType',
@@ -107,18 +82,15 @@ 
         'NetClientDriver',
         'NumaOptions',
         'ObjectType',
-        'PCDIMMDeviceInfoWrapper',
         'PciMemoryRegion',
         'QCryptoAkCipherKeyType',
         'QCryptoAkCipherOptions',
         'QCryptodevBackendServiceType',
         'QKeyCode',
-        'QKeyCodeWrapper',
         'Qcow2OverlapCheckFlags',
         'RbdAuthMode',
         'RbdEncryptionCreateOptions',
         'RbdImageEncryptionFormat',
-        'SgxEPCDeviceInfoWrapper',
         'SocketAddressLegacy',
         'SshHostKeyCheck',
         'StatsFilter',
@@ -126,16 +98,10 @@ 
         'String',
         'StringWrapper',
         'SysEmuTarget',
-        'TPMEmulatorOptionsWrapper',
-        'TPMPassthroughOptionsWrapper',
         'ThrottleGroupProperties',
         'TransactionAction',
-        'UnixSocketAddressWrapper',
-        'VirtioMEMDeviceInfoWrapper',
-        'VirtioPMEMDeviceInfoWrapper',
         'VncPrimaryAuth',
         'VncVencryptSubAuth',
-        'VsockSocketAddressWrapper',
         'X86CPURegister32',
         'XDbgBlockGraph',
         'YankInstance',
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 6213154525..c3b616731d 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -119,6 +119,8 @@ 
 ##
 # @InetSocketAddressWrapper:
 #
+# @data: internet domain socket address
+#
 # Since: 1.3
 ##
 { 'struct': 'InetSocketAddressWrapper',
@@ -127,6 +129,8 @@ 
 ##
 # @UnixSocketAddressWrapper:
 #
+# @data: UNIX domain socket address
+#
 # Since: 1.3
 ##
 { 'struct': 'UnixSocketAddressWrapper',
@@ -135,6 +139,8 @@ 
 ##
 # @VsockSocketAddressWrapper:
 #
+# @data: VSOCK domain socket address
+#
 # Since: 2.8
 ##
 { 'struct': 'VsockSocketAddressWrapper',
diff --git a/qapi/tpm.json b/qapi/tpm.json
index a754455ca5..f9c1e866e7 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -102,6 +102,8 @@ 
 ##
 # @TPMPassthroughOptionsWrapper:
 #
+# @data: Information about the TPM passthrough type
+#
 # Since: 1.5
 ##
 { 'struct': 'TPMPassthroughOptionsWrapper',
@@ -111,6 +113,8 @@ 
 ##
 # @TPMEmulatorOptionsWrapper:
 #
+# @data: Information about the TPM emulator type
+#
 # Since: 2.11
 ##
 { 'struct': 'TPMEmulatorOptionsWrapper',
diff --git a/qapi/ui.json b/qapi/ui.json
index a0158baf23..1eccad0a83 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -990,6 +990,8 @@ 
 ##
 # @IntWrapper:
 #
+# @data: a numeric key code
+#
 # Since: 1.3
 ##
 { 'struct': 'IntWrapper',
@@ -998,6 +1000,8 @@ 
 ##
 # @QKeyCodeWrapper:
 #
+# @data: An enumeration of key name
+#
 # Since: 1.3
 ##
 { 'struct': 'QKeyCodeWrapper',
@@ -1175,6 +1179,8 @@ 
 ##
 # @InputKeyEventWrapper:
 #
+# @data: Keyboard input event
+#
 # Since: 2.0
 ##
 { 'struct': 'InputKeyEventWrapper',
@@ -1183,6 +1189,8 @@ 
 ##
 # @InputBtnEventWrapper:
 #
+# @data: Pointer button input event
+#
 # Since: 2.0
 ##
 { 'struct': 'InputBtnEventWrapper',
@@ -1191,6 +1199,8 @@ 
 ##
 # @InputMoveEventWrapper:
 #
+# @data: Pointer motion input event
+#
 # Since: 2.0
 ##
 { 'struct': 'InputMoveEventWrapper',
@@ -1199,6 +1209,8 @@ 
 ##
 # @InputMultiTouchEventWrapper:
 #
+# @data: MultiTouch input event
+#
 # Since: 8.1
 ##
 { 'struct': 'InputMultiTouchEventWrapper',