From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: peter.maydell@linaro.org, "Daniel P . Berrangé" <berrange@redhat.com>
Subject: [PULL 12/18] qapi: Plug trivial documentation holes around former simple unions
Date: Mon, 12 Feb 2024 10:14:30 +0100 [thread overview]
Message-ID: <20240212091436.688598-13-armbru@redhat.com> (raw)
In-Reply-To: <20240212091436.688598-1-armbru@redhat.com>
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>
Message-ID: <20240205074709.3613229-13-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@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(-)
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',
--
2.43.0
next prev parent reply other threads:[~2024-02-12 9:19 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-02-12 9:14 [PULL 00/18] QAPI patches patches for 2024-02-12 Markus Armbruster
2024-02-12 9:14 ` [PULL 01/18] docs/devel/qapi-code-gen: Normalize version refs x.y.0 to just x.y Markus Armbruster
2024-02-12 9:14 ` [PULL 02/18] docs/devel/qapi-code-gen: Tweak doc comment whitespace Markus Armbruster
2024-02-12 9:14 ` [PULL 03/18] qapi/block-core: Fix BlockLatencyHistogramInfo doc markup Markus Armbruster
2024-02-12 9:14 ` [PULL 04/18] qapi: Indent tagged doc comment sections properly Markus Armbruster
2024-02-12 9:14 ` [PULL 05/18] sphinx/qapidoc: Drop code to generate doc for simple union tag Markus Armbruster
2024-02-12 9:14 ` [PULL 06/18] qapi: Require member documentation (with loophole) Markus Armbruster
2024-02-12 9:14 ` [PULL 07/18] qga/qapi-schema: Clean up documentation of guest-set-memory-blocks Markus Armbruster
2024-02-12 9:14 ` [PULL 08/18] qga/qapi-schema: Clean up documentation of guest-set-vcpus Markus Armbruster
2024-02-12 9:14 ` [PULL 09/18] qga/qapi-schema: Plug trivial documentation holes Markus Armbruster
2024-02-12 9:14 ` [PULL 10/18] qapi/yank: Clean up documentaion of yank Markus Armbruster
2024-02-12 9:14 ` [PULL 11/18] qapi/dump: Clean up documentation of DumpGuestMemoryCapability Markus Armbruster
2024-02-12 9:14 ` Markus Armbruster [this message]
2024-02-12 9:14 ` [PULL 13/18] qapi: Improve documentation of file descriptor socket addresses Markus Armbruster
2024-02-12 9:14 ` [PULL 14/18] qapi: Move @String out of common.json to discourage reuse Markus Armbruster
2024-02-12 9:14 ` [PULL 15/18] qapi: Add missing union tag documentation Markus Armbruster
2024-02-12 9:14 ` [PULL 16/18] qapi/migration: Add missing tls-authz documentation Markus Armbruster
2024-02-12 9:14 ` [PULL 17/18] MAINTAINERS: Cover qapi/cxl.json Markus Armbruster
2024-02-12 9:14 ` [PULL 18/18] MAINTAINERS: Cover qapi/stats.json Markus Armbruster
2024-02-13 13:55 ` [PULL 00/18] QAPI patches patches for 2024-02-12 Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240212091436.688598-13-armbru@redhat.com \
--to=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=peter.maydell@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).