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

[PATCH 0/6] 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
    cryptodev       QCryptodevBackendServiceType        5
    cxl             CxlCorErrorType                     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: DummyVirtioForceArrays is purely internal, and should be elided
from the manual instead, but that's a different project.

Markus Armbruster (6):
  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/char.json       | 44 ++++++++++++++++++++++++++++----------------
 qapi/common.json     | 14 +++++++++++++-
 qapi/crypto.json     |  4 ++++
 qapi/introspect.json | 16 ++++++++++++++++
 qapi/pci.json        |  2 ++
 qapi/pragma.json     |  9 +--------
 qapi/rocker.json     |  4 ++++
 7 files changed, 68 insertions(+), 25 deletions(-)

-- 
2.45.0

[PATCH 1/6] 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..8a4a87c95c 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 v1.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 59fbe74b8c..39a424303b 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -46,7 +46,6 @@
         'BlockdevSnapshotSyncWrapper',
         'BlockdevSnapshotWrapper',
         'BlockdevVmdkAdapterType',
-        'ChardevBackendKind',
         'CpuS390Entitlement',
         'CpuS390Polarization',
         'CpuS390State',
-- 
2.45.0

[PATCH 2/6] 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>
---
 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 39a424303b..6ff135d8d2 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -55,7 +55,6 @@
         'DummyBlockCoreForceArrays',
         'DummyForceArrays',
         'DummyVirtioForceArrays',
-        'GrabToggleKeys',
         'HotKeyMod',
         'ImageInfoSpecificKind',
         'InputAxis',
-- 
2.45.0

[PATCH 3/6] 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>
---
 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 97e02dbd59..67f5855a96 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -610,6 +610,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 6ff135d8d2..fd6bdcaa6d 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -67,7 +67,6 @@
         'NetClientDriver',
         'ObjectType',
         'PciMemoryRegion',
-        'QCryptoAkCipherKeyType',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.45.0

[PATCH 4/6] 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>
---
 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 fd6bdcaa6d..cc218f64b8 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -61,7 +61,6 @@
         'InputButton',
         'IscsiHeaderDigest',
         'IscsiTransport',
-        'JSONType',
         'KeyValueKind',
         'MemoryDeviceInfoKind',
         'NetClientDriver',
-- 
2.45.0

[PATCH 5/6] 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>
---
 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 cc218f64b8..1570d6bcc6 100644
--- a/qapi/pragma.json
+++ b/qapi/pragma.json
@@ -65,7 +65,6 @@
         'MemoryDeviceInfoKind',
         'NetClientDriver',
         'ObjectType',
-        'PciMemoryRegion',
         'QCryptodevBackendServiceType',
         'QKeyCode',
         'RbdAuthMode',
-- 
2.45.0

[PATCH 6/6] 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>
---
 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 1570d6bcc6..ae9eaa2657 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 6950ca9602..f1a87243fa 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.45.0

Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 2861 bytes --]

On Thu, Aug 8, 2024 at 2:26 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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..8a4a87c95c 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 v1.5)
>

Remove the "v"?


> +#
> +# @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 59fbe74b8c..39a424303b 100644
> --- a/qapi/pragma.json
> +++ b/qapi/pragma.json
> @@ -46,7 +46,6 @@
>          'BlockdevSnapshotSyncWrapper',
>          'BlockdevSnapshotWrapper',
>          'BlockdevVmdkAdapterType',
> -        'ChardevBackendKind',
>          'CpuS390Entitlement',
>          'CpuS390Polarization',
>          'CpuS390State',
> --
> 2.45.0
>

It'd be nice if these included some kind of cross-reference to
documentation for the backends in question, but this is better than "(Not
documented)", so it's not time to be picky.

ACK

--js

[-- Attachment #2: Type: text/html, Size: 3801 bytes --]

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 4187 bytes --]

On Thu, Aug 8, 2024 at 2:26 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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
>     cryptodev       QCryptodevBackendServiceType        5
>     cxl             CxlCorErrorType                     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: DummyVirtioForceArrays is purely internal, and should be elided
> from the manual instead, but that's a different project.
>
> Markus Armbruster (6):
>   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/char.json       | 44 ++++++++++++++++++++++++++++----------------
>  qapi/common.json     | 14 +++++++++++++-
>  qapi/crypto.json     |  4 ++++
>  qapi/introspect.json | 16 ++++++++++++++++
>  qapi/pci.json        |  2 ++
>  qapi/pragma.json     |  9 +--------
>  qapi/rocker.json     |  4 ++++
>  7 files changed, 68 insertions(+), 25 deletions(-)
>
> --
> 2.45.0
>

I don't maintain any of these, but looks fine enough to me over being
undocumented.

ACK.

~~js

[-- Attachment #2: Type: text/html, Size: 5634 bytes --]

Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Thu, Aug 8, 2024 at 2:26 PM Markus Armbruster <armbru@redhat.com> wrote:
>
>> 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..8a4a87c95c 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 v1.5)
>>
>
> Remove the "v"?

Yes.  Good catch!

>> +#
>> +# @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 59fbe74b8c..39a424303b 100644
>> --- a/qapi/pragma.json
>> +++ b/qapi/pragma.json
>> @@ -46,7 +46,6 @@
>>          'BlockdevSnapshotSyncWrapper',
>>          'BlockdevSnapshotWrapper',
>>          'BlockdevVmdkAdapterType',
>> -        'ChardevBackendKind',
>>          'CpuS390Entitlement',
>>          'CpuS390Polarization',
>>          'CpuS390State',
>> --
>> 2.45.0
>>
>
> It'd be nice if these included some kind of cross-reference to
> documentation for the backends in question, but this is better than "(Not
> documented)", so it's not time to be picky.

Same for any enum that's used as union tag?

> ACK

Thank you!

Re: [PATCH 2/6] qapi/common: Supply missing member documentation

[Philippe Mathieu-Daudé]

On 8/8/24 20:26, Markus Armbruster wrote:
> 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>
> ---
>   qapi/common.json | 14 +++++++++++++-
>   qapi/pragma.json |  1 -
>   2 files changed, 13 insertions(+), 2 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

Re: [PATCH 3/6] qapi/crypto: Supply missing member documentation

[Philippe Mathieu-Daudé]

On 8/8/24 20:26, Markus Armbruster wrote:
> 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>
> ---
>   qapi/crypto.json | 4 ++++
>   qapi/pragma.json | 1 -
>   2 files changed, 4 insertions(+), 1 deletion(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

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

[Philippe Mathieu-Daudé]

On 8/8/24 20:26, 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>
> ---
>   qapi/pci.json    | 2 ++
>   qapi/pragma.json | 1 -
>   2 files changed, 2 insertions(+), 1 deletion(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

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

[Philippe Mathieu-Daudé]

On 8/8/24 20:26, Markus Armbruster wrote:
> 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>
> ---
>   qapi/pragma.json | 4 +---
>   qapi/rocker.json | 4 ++++
>   2 files changed, 5 insertions(+), 3 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>

Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[Philippe Mathieu-Daudé]

Hi Markus,

On 8/8/24 20:26, Markus Armbruster wrote:
> 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..8a4a87c95c 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 v1.5)
> +#
> +# @ringbuf: memory ring buffer (since 1.6)
> +#
> +# @memory: synonym for @ringbuf (since 1.5)

What is the rule to sort the members?

Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[Markus Armbruster]

Philippe Mathieu-Daudé <philmd@linaro.org> writes:

> Hi Markus,
>
> On 8/8/24 20:26, Markus Armbruster wrote:
>> 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..8a4a87c95c 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 v1.5)
>> +#
>> +# @ringbuf: memory ring buffer (since 1.6)
>> +#
>> +# @memory: synonym for @ringbuf (since 1.5)
>
> What is the rule to sort the members?

I like to keep the member descriptions in the same order as their
definitions in 'data'.

As to the order in 'data': sometimes there's a "natural" order or
grouping, and sometimes alphabetical is best.  However, we too often add
members without giving order a thought, commonly at the end.

Hope this helps!

Re: [PATCH 4/6] qapi/introspect: Supply missing member documentation

[Eric Blake]

On Thu, Aug 08, 2024 at 08:26:34PM GMT, Markus Armbruster wrote:
> 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>
> ---
>  qapi/introspect.json | 16 ++++++++++++++++
>  qapi/pragma.json     |  1 -
>  2 files changed, 16 insertions(+), 1 deletion(-)

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH 1/6] qapi/char: Supply missing member documentation

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 3860 bytes --]

On Fri, Aug 9, 2024 at 5:12 AM Markus Armbruster <armbru@redhat.com> wrote:

> Philippe Mathieu-Daudé <philmd@linaro.org> writes:
>
> > Hi Markus,
> >
> > On 8/8/24 20:26, Markus Armbruster wrote:
> >> 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..8a4a87c95c 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 v1.5)
> >> +#
> >> +# @ringbuf: memory ring buffer (since 1.6)
> >> +#
> >> +# @memory: synonym for @ringbuf (since 1.5)
> >
> > What is the rule to sort the members?
>
> I like to keep the member descriptions in the same order as their
> definitions in 'data'.
>
> As to the order in 'data': sometimes there's a "natural" order or
> grouping, and sometimes alphabetical is best.  However, we too often add
> members without giving order a thought, commonly at the end.
>
> Hope this helps!
>

What Markus says is correct. Some additional clarification:

The order is not part of the API (for QAPI/QMP), so there's no rule.
Matching the doc and definition orders is often the "nicest" but it is not
enforced.

The definition orders usually tend to "grow downwards" like a struct, but
that's only a tendency and not a rule.

Future developments may or may not impose an order; it's often contested.
At times, Marc-Andre and I have desired to establish a canon order for the
purposes of third party APIs, but QAPI as it stands is militant about order
being unimportant and there are no immediate plans to change that, only
rumblings and desires that stand at odds with Markus's desire to keep order
be unimportant.

(Which, to be clear, is not me belly-aching about Markus's excellent
maintainership of QAPI; just pointing out that there is some tension on
that requirement that remains more or less unsettled.)

--js

[-- Attachment #2: Type: text/html, Size: 5191 bytes --]