[PATCH v2 0/8] qapi: Supply some of the missing member documentation

[PATCH v2 0/8] qapi: Supply some of the missing member documentation

[Markus Armbruster]

This series gets a few of modules off the pragma
documentation-exceptions list of shame that require minimal effort.

Many undocumented members still remain:

    module          type or command                     #missing
    ------------------------------------------------------------
    audio           AudiodevDriver                      12
    block-core      BlkdebugEvent                       43
                    BlockdevDriver                      39
                    BlockdevQcow2EncryptionFormat       1
                    BlockdevVmdkAdapterType             4
                    DummyBlockCoreForceArrays           1
                    ImageInfoSpecificKind               2
                    IscsiHeaderDigest                   4
                    IscsiTransport                      2
                    RbdAuthMode                         2
                    RbdImageEncryptionFormat            2
                    ThrottleGroupProperties             19
                    XDbgBlockGraph                      2
                    blockdev-reopen			1
    machine-common  CpuS390Entitlement                  4
    machine-target  CpuS390Polarization                 2
    machine         CpuS390State                        5
                    DummyForceArrays                    1
                    MemoryDeviceInfoKind                1
                    SysEmuTarget                        27
                    X86CPURegister32                    8
    net             NetClientDriver                     10
                    String                              1
    qom             ObjectType                          48
    transaction     AbortWrapper                        1
                    BlockDirtyBitmapAddWrapper          1
                    BlockDirtyBitmapMergeWrapper        1
                    BlockDirtyBitmapWrapper             1
                    BlockdevBackupWrapper               1
                    BlockdevSnapshotInternalWrapper     1
                    BlockdevSnapshotSyncWrapper         1
                    BlockdevSnapshotWrapper             1
                    DriveBackupWrapper                  1
    ui              DisplayProtocol                     2
                    HotKeyMod                           3
                    InputAxis                           2
                    InputButton                         7
                    KeyValueKind                        2
                    QKeyCode                            119
                    VncPrimaryAuth                      9
                    VncVencryptSubAuth                  9
    virtio          DummyVirtioForceArrays              1
    yank            YankInstanceType                    3
    qga             GuestNVMeSmart                      25

Note: The Dummy*ForceArrays are purely internal, and should be elided
from the manual instead, but that's a different project.

Based on my "[PULL 00/19] QAPI patches patches for 2024-09-10" rather
than current master to avoid trivial conflicts in qapi/pragma.json.

Based-on: <20240910164714.1993531-1-armbru@redhat.com>

v2:
* Rebased on latest QAPI PR
* PATCH 1: Tody up a "since" while there [John Snow]
* PATCH 7+8: New

Markus Armbruster (7):
  qapi/char: Supply missing member documentation
  qapi/common: Supply missing member documentation
  qapi/crypto: Supply missing member documentation
  qapi/introspect: Supply missing member documentation
  qapi/pci: Supply missing member documentation
  qapi/rocker: Supply missing member documentation
  qapi/cxl: Supply missing member documentation

Zhenwei Pi (1):
  qapi: Document QCryptodevBackendServiceType

 qapi/char.json       | 44 ++++++++++++++++++++++++++++----------------
 qapi/common.json     | 14 +++++++++++++-
 qapi/crypto.json     |  4 ++++
 qapi/cryptodev.json  | 10 ++++++++++
 qapi/cxl.json        |  3 +++
 qapi/introspect.json | 16 ++++++++++++++++
 qapi/pci.json        |  2 ++
 qapi/pragma.json     | 11 +----------
 qapi/rocker.json     |  4 ++++
 9 files changed, 81 insertions(+), 27 deletions(-)

-- 
2.46.0

[PATCH v2 1/8] qapi/char: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document several members of ChardevBackendKind,
their description in the QEMU QMP Reference manual is "Not
documented".  Fix that, and improve the existing member documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/char.json   | 44 ++++++++++++++++++++++++++++----------------
 qapi/pragma.json |  1 -
 2 files changed, 28 insertions(+), 17 deletions(-)

diff --git a/qapi/char.json b/qapi/char.json
index ef58445cee..0d6de1ee35 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -434,37 +434,49 @@
 ##
 # @ChardevBackendKind:
 #
-# @pipe: Since 1.5
+# @file: regular files
 #
-# @udp: Since 1.5
+# @serial: serial host device
 #
-# @mux: Since 1.5
+# @parallel: parallel host device
 #
-# @msmouse: Since 1.5
+# @pipe: pipes (since 1.5)
 #
-# @wctablet: Since 2.9
+# @socket: stream socket
 #
-# @braille: Since 1.5
+# @udp: datagram socket (since 1.5)
 #
-# @testdev: Since 2.2
+# @pty: pseudo-terminal
 #
-# @stdio: Since 1.5
+# @null: provides no input, throws away output
 #
-# @console: Since 1.5
+# @mux: (since 1.5)
 #
-# @spicevmc: Since 1.5
+# @msmouse: emulated Microsoft serial mouse (since 1.5)
 #
-# @spiceport: Since 1.5
+# @wctablet: emulated Wacom Penpartner serial tablet (since 2.9)
 #
-# @qemu-vdagent: Since 6.1
+# @braille: Baum Braille device (since 1.5)
 #
-# @dbus: Since 7.0
+# @testdev: device for test-suite control (since 2.2)
 #
-# @vc: v1.5
+# @stdio: standard I/O (since 1.5)
 #
-# @ringbuf: Since 1.6
+# @console: Windows console (since 1.5)
 #
-# @memory: Since 1.5
+# @spicevmc: spice vm channel (since 1.5)
+#
+# @spiceport: Spice port channel (since 1.5)
+#
+# @qemu-vdagent: Spice vdagent (since 6.1)
+#
+# @dbus: D-Bus channel (since 7.0)
+#
+# @vc: virtual console (since 1.5)
+#
+# @ringbuf: memory ring buffer (since 1.6)
+#
+# @memory: synonym for @ringbuf (since 1.5)
 #
 # Features:
 #
diff --git a/qapi/pragma.json b/qapi/pragma.json
index fad3a31628..d5ae397293 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,7 +46,6 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'ChardevBackendKind',
         'CxlCorErrorType',
         'DisplayProtocol',
         'DriveBackupWrapper',
-- 
2.46.0

[PATCH v2 2/8] qapi/common: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of GrabToggleKeys, their
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 qapi/common.json | 14 +++++++++++++-
 qapi/pragma.json |  1 -
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/qapi/common.json b/qapi/common.json
index 7558ce5430..6ffc7a3789 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -183,7 +183,19 @@
 ##
 # @GrabToggleKeys:
 #
-# Keys to toggle input-linux between host and guest.
+# Key combinations to toggle input-linux between host and guest.
+#
+# @ctrl-ctrl: left and right control key
+#
+# @alt-alt: left and right alt key
+#
+# @shift-shift: left and right shift key
+#
+# @meta-meta: left and right meta key
+#
+# @scrolllock: scroll lock key
+#
+# @ctrl-scrolllock: either control key and scroll lock key
 #
 # Since: 4.0
 ##
diff --git a/qapi/pragma.json b/qapi/pragma.json
index d5ae397293..f03b9cc444 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -52,7 +52,6 @@
         'DummyBlockCoreForceArrays',
         'DummyForceArrays',
         'DummyVirtioForceArrays',
-        'GrabToggleKeys',
         'HotKeyMod',
         'ImageInfoSpecificKind',
         'InputAxis',
-- 
2.46.0

[PATCH v2 3/8] qapi/crypto: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of QCryptoAkCipherKeyType,
their description in the QEMU QMP Reference manual is "Not
documented".  Fix that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 qapi/crypto.json | 4 ++++
 qapi/pragma.json | 1 -
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/qapi/crypto.json b/qapi/crypto.json
index 867b09d322..9431522768 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -602,6 +602,10 @@
 #
 # The type of asymmetric keys.
 #
+# @public: public key
+#
+# @private: private key
+#
 # Since: 7.1
 ##
 { 'enum': 'QCryptoAkCipherKeyType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index f03b9cc444..625eac99df 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -64,7 +64,6 @@
         'NetClientDriver',
         'ObjectType',
         'PciMemoryRegion',
-        'QCryptoAkCipherKeyType',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.46.0

[PATCH v2 4/8] qapi/introspect: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the members of JSONType, their
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/introspect.json | 16 ++++++++++++++++
 qapi/pragma.json     |  1 -
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/qapi/introspect.json b/qapi/introspect.json
index 14df049580..01bb242947 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -127,6 +127,22 @@
 # section 1, plus 'int' (split off 'number'), plus the obvious top
 # type 'value'.
 #
+# @string: JSON string
+#
+# @number: JSON number
+#
+# @int: JSON number that is an integer
+#
+# @boolean: literal ``false`` or ``true``
+#
+# @null: literal ``null``
+#
+# @object: JSON object
+#
+# @array: JSON array
+#
+# @value: any JSON value
+#
 # Since: 2.5
 ##
 { 'enum': 'JSONType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 625eac99df..7b0e12f42b 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -58,7 +58,6 @@
         'InputButton',
         'IscsiHeaderDigest',
         'IscsiTransport',
-        'JSONType',
         'KeyValueKind',
         'MemoryDeviceInfoKind',
         'NetClientDriver',
-- 
2.46.0

[PATCH v2 5/8] qapi/pci: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document a member of PciMemoryRegion, its
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 qapi/pci.json    | 2 ++
 qapi/pragma.json | 1 -
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/qapi/pci.json b/qapi/pci.json
index 78bee57b77..dc85a41d28 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -33,6 +33,8 @@
 #     - 'io' if the region is a PIO region
 #     - 'memory' if the region is a MMIO region
 #
+# @address: memory address
+#
 # @size: memory size
 #
 # @prefetch: if @type is 'memory', true if the memory is prefetchable
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 7b0e12f42b..baeae5bf52 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -62,7 +62,6 @@
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'PciMemoryRegion',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.46.0

[PATCH v2 6/8] qapi/rocker: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document the argument of query-rocker and
query-rocker-ports, their description in the QEMU QMP Reference manual
is "Not documented".  Fix that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 qapi/pragma.json | 4 +---
 qapi/rocker.json | 4 ++++
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/qapi/pragma.json b/qapi/pragma.json
index baeae5bf52..feb7981700 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -78,9 +78,7 @@
         'X86CPURegister32',
         'XDbgBlockGraph',
         'YankInstanceType',
-        'blockdev-reopen',
-        'query-rocker',
-        'query-rocker-ports' ],
+        'blockdev-reopen' ],
     # Externally visible types whose member names may use uppercase
     'member-name-exceptions': [     # visible in:
         'ACPISlotType',             # query-acpi-ospm-status
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 73c7363b16..51aa5b4930 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -26,6 +26,8 @@
 #
 # Return rocker switch information.
 #
+# @name: switch name
+#
 # Returns: @Rocker information
 #
 # Since: 2.4
@@ -94,6 +96,8 @@
 #
 # Return rocker switch port information.
 #
+# @name: port name
+#
 # Returns: a list of @RockerPort information
 #
 # Since: 2.4
-- 
2.46.0

[PATCH v2 7/8] qapi/cxl: Supply missing member documentation

[Markus Armbruster]

Since we neglect to document a member of CxlCorErrorType, its
description in the QEMU QMP Reference manual is "Not documented".  Fix
that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/cxl.json    | 3 +++
 qapi/pragma.json | 1 -
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/qapi/cxl.json b/qapi/cxl.json
index e9315d5b4d..9f65589bce 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -326,6 +326,9 @@
 # @crc-threshold: Component specific and applicable to 68 byte Flit
 #     mode only.
 #
+# @retry-threshold: Retry threshold hit in the Local Retry State
+#     Machine, 68B Flits only.
+#
 # @cache-poison-received: Received poison from a peer on CXL.cache.
 #
 # @mem-poison-received: Received poison from a peer on CXL.mem
diff --git a/qapi/pragma.json b/qapi/pragma.json
index feb7981700..108e574678 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,7 +46,6 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'CxlCorErrorType',
         'DisplayProtocol',
         'DriveBackupWrapper',
         'DummyBlockCoreForceArrays',
-- 
2.46.0

[PATCH v2 8/8] qapi: Document QCryptodevBackendServiceType

[Markus Armbruster]

From: zhenwei pi <pizhenwei@bytedance.com>

QCryptodevBackendServiceType was introduced by
bc304a6442e (cryptodev: Introduce server type in QAPI). However there
is a lack of member description.

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: zhenwei pi <pizhenwei@bytedance.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Drop QCryptodevBackendServiceType from pragma documentation-exceptions]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/cryptodev.json | 10 ++++++++++
 qapi/pragma.json    |  1 -
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 5e417340dc..04d0e21d20 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -27,6 +27,16 @@
 #
 # The supported service types of a crypto device.
 #
+# @cipher: Symmetric Key Cipher service
+#
+# @hash: Hash service
+#
+# @mac: Message Authentication Codes service
+#
+# @aead: Authenticated Encryption with Associated Data service
+#
+# @akcipher: Asymmetric Key Cipher service
+#
 # Since: 8.0
 ##
 { 'enum': 'QCryptodevBackendServiceType',
diff --git a/qapi/pragma.json b/qapi/pragma.json
index 108e574678..023a2ef7bc 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -61,7 +61,6 @@
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
         'RbdImageEncryptionFormat',
-- 
2.46.0

Re: [PATCH v2 5/8] qapi/pci: Supply missing member documentation

[Michael S. Tsirkin]

On Wed, Sep 11, 2024 at 01:25:42PM +0200, Markus Armbruster wrote:
> Since we neglect to document a member of PciMemoryRegion, its
> description in the QEMU QMP Reference manual is "Not documented".  Fix
> that.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

Reviewed-by: Michael S. Tsirkin <mst@redhat.com>


can you merge this?

> ---
>  qapi/pci.json    | 2 ++
>  qapi/pragma.json | 1 -
>  2 files changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/qapi/pci.json b/qapi/pci.json
> index 78bee57b77..dc85a41d28 100644
> --- a/qapi/pci.json
> +++ b/qapi/pci.json
> @@ -33,6 +33,8 @@
>  #     - 'io' if the region is a PIO region
>  #     - 'memory' if the region is a MMIO region
>  #
> +# @address: memory address
> +#
>  # @size: memory size
>  #
>  # @prefetch: if @type is 'memory', true if the memory is prefetchable
> diff --git a/qapi/pragma.json b/qapi/pragma.json
> index 7b0e12f42b..baeae5bf52 100644
> --- a/qapi/pragma.json
> +++ b/qapi/pragma.json
> @@ -62,7 +62,6 @@
>          'MemoryDeviceInfoKind',
>          'NetClientDriver',
>          'ObjectType',
> -        'PciMemoryRegion',
>          'QCryptodevBackendServiceType',
>          'QKeyCode',
>          'RbdAuthMode',
> -- 
> 2.46.0

Re: [PATCH v2 5/8] qapi/pci: Supply missing member documentation

[Markus Armbruster]

"Michael S. Tsirkin" <mst@redhat.com> writes:

> On Wed, Sep 11, 2024 at 01:25:42PM +0200, Markus Armbruster wrote:
>> Since we neglect to document a member of PciMemoryRegion, its
>> description in the QEMU QMP Reference manual is "Not documented".  Fix
>> that.
>> 
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
>
> Reviewed-by: Michael S. Tsirkin <mst@redhat.com>
>
>
> can you merge this?

Gladly!

Re: [PATCH v2 0/8] qapi: Supply some of the missing member documentation

[Markus Armbruster]

Qeueued.  I'm going to sit on it for a few more days in the hope of
getting PATCH 1+7 reviewed, too.