[PULL 0/5] QAPI patches patches for 2024-02-03

[PULL 0/5] QAPI patches patches for 2024-02-03

[Markus Armbruster]

The following changes since commit 29b008927ef6e3fbb70e6607b25d3fcae26a5190:

  Merge tag 'pull-nic-config-2-20240202' of git://git.infradead.org/users/dwmw2/qemu into staging (2024-02-02 16:47:36 +0000)

are available in the Git repository at:

  https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-02-03

for you to fetch changes up to 3424ed6caf9759eb57405d965537fd5f3d70026b:

  qga/qapi-schema: Move command description right after command name (2024-02-03 09:20:33 +0100)

----------------------------------------------------------------
QAPI patches patches for 2024-02-03

----------------------------------------------------------------
Markus Armbruster (5):
      qapi: Drop redundant documentation of inherited members
      qapi: Drop redundant documentation of conditional
      qapi: Elide "Potential additional modes" from generated docs
      qga: Move type description right after type name
      qga/qapi-schema: Move command description right after command name

 qapi/block-core.json   |  6 ++----
 qapi/block-export.json | 11 ++++++-----
 qapi/introspect.json   |  2 --
 qapi/misc-target.json  |  2 --
 qga/qapi-schema.json   | 18 +++++++++---------
 5 files changed, 17 insertions(+), 22 deletions(-)

-- 
2.43.0

[PULL 1/5] qapi: Drop redundant documentation of inherited members

[Markus Armbruster]

Documentation generated for SchemaInfo looks like

    The members of "SchemaInfoBuiltin" when "meta-type" is ""builtin""
    The members of "SchemaInfoEnum" when "meta-type" is ""enum""
    The members of "SchemaInfoArray" when "meta-type" is ""array""
    The members of "SchemaInfoObject" when "meta-type" is ""object""
    The members of "SchemaInfoAlternate" when "meta-type" is ""alternate""
    The members of "SchemaInfoCommand" when "meta-type" is ""command""
    The members of "SchemaInfoEvent" when "meta-type" is ""event""
    Additional members depend on the value of "meta-type".

The last line became redundant when commit 88f63467c57 (qapi2texi:
Generate reference to base type members) added the lines preceding it.
Drop it.

BlockdevOptions has the same issue.  Drop

    Remaining options are determined by the block driver.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/block-core.json | 2 --
 qapi/introspect.json | 2 --
 2 files changed, 4 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 48c181e55d..530c4af50f 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4665,8 +4665,6 @@
 # @force-share: force share all permission on added nodes.  Requires
 #     read-only=true.  (Since 2.10)
 #
-# Remaining options are determined by the block driver.
-#
 # Since: 2.9
 ##
 { 'union': 'BlockdevOptions',
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 8df1ce85ed..b041b02ba8 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -93,8 +93,6 @@
 #     particular order.  (since 4.1 for object types, 4.2 for
 #     commands, 5.0 for the rest)
 #
-# Additional members depend on the value of @meta-type.
-#
 # Since: 2.5
 ##
 { 'union': 'SchemaInfo',
-- 
2.43.0

[PULL 2/5] qapi: Drop redundant documentation of conditional

[Markus Armbruster]

Documentation generated for dump-skeys contains

    This command is only supported on s390 architecture.

and

    If
    ~~

    "TARGET_S390X"

The former became redundant in commit 901a34a400a (qapi: add 'If:'
section to generated documentation) added the latter.  Drop the
former.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-3-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/misc-target.json | 2 --
 1 file changed, 2 deletions(-)

diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 9195e7d26b..03e83c053f 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -237,8 +237,6 @@
 #
 # @filename: the path to the file to dump to
 #
-# This command is only supported on s390 architecture.
-#
 # Since: 2.5
 #
 # Example:
-- 
2.43.0

[PULL 3/5] qapi: Elide "Potential additional modes" from generated docs

[Markus Armbruster]

Documentation of BlockExportRemoveMode has

    Potential additional modes to be added in the future:

    hide: Just hide export from new clients, leave existing connections
    as is.  Remove export after all clients are disconnected.

    soft: Hide export from new clients, answer with ESHUTDOWN for all
    further requests from existing clients.

I think this is useful only for developers.  Elide it from generated
documentation by turning it into a TODO section.

This effectively reverts my own commit b71fd73cc45 (Revert "qapi:
BlockExportRemoveMode: move comments to TODO").  At the time, I was
about to elide TODO sections from the generated manual, I wasn't sure
about this one, and decided to avoid change.  And now I've made up my
mind.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-4-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
 qapi/block-export.json | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 7874a49ba7..e063e9255a 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -266,13 +266,14 @@
 #
 # @hard: Drop all connections immediately and remove export.
 #
-# Potential additional modes to be added in the future:
+# TODO: Potential additional modes to be added in the future:
 #
-# hide: Just hide export from new clients, leave existing connections
-# as is.  Remove export after all clients are disconnected.
+#     - hide: Just hide export from new clients, leave existing
+#       connections as is.  Remove export after all clients are
+#       disconnected.
 #
-# soft: Hide export from new clients, answer with ESHUTDOWN for all
-# further requests from existing clients.
+#     - soft: Hide export from new clients, answer with ESHUTDOWN for
+#       all further requests from existing clients.
 #
 # Since: 2.12
 ##
-- 
2.43.0

[PULL 4/5] qga: Move type description right after type name

[Markus Armbruster]

Documentation of type BlockdevOptionsIscsi describes the type's
purpose after its members.  Everywhere else, we do it the other way
round.  Move it for consistency.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-5-armbru@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
---
 qapi/block-core.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 530c4af50f..781c9bd03e 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4070,6 +4070,8 @@
 ##
 # @BlockdevOptionsIscsi:
 #
+# Driver specific block device options for iscsi
+#
 # @transport: The iscsi transport type
 #
 # @portal: The address of the iscsi portal
@@ -4094,8 +4096,6 @@
 # @timeout: Timeout in seconds after which a request will timeout.  0
 #     means no timeout and is the default.
 #
-# Driver specific block device options for iscsi
-#
 # Since: 2.9
 ##
 { 'struct': 'BlockdevOptionsIscsi',
-- 
2.43.0

[PULL 5/5] qga/qapi-schema: Move command description right after command name

[Markus Armbruster]

Documentation of commands guest-ssh-get-authorized-keys,
guest-ssh-add-authorized-keys, and guest-ssh-remove-authorized-keys
describes the command's purpose after its arguments.  Everywhere else,
we do it the other way round.  Move it for consistency.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240129115008.674248-6-armbru@redhat.com>
Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>
---
 qga/qapi-schema.json | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 876e2a8ea8..50b0a558c7 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -1565,11 +1565,11 @@
 ##
 # @guest-ssh-get-authorized-keys:
 #
-# @username: the user account to add the authorized keys
-#
 # Return the public keys from user .ssh/authorized_keys on Unix
 # systems (not implemented for other systems).
 #
+# @username: the user account to add the authorized keys
+#
 # Returns: @GuestAuthorizedKeys
 #
 # Since: 5.2
@@ -1582,6 +1582,9 @@
 ##
 # @guest-ssh-add-authorized-keys:
 #
+# Append public keys to user .ssh/authorized_keys on Unix systems (not
+# implemented for other systems).
+#
 # @username: the user account to add the authorized keys
 #
 # @keys: the public keys to add (in OpenSSH/sshd(8) authorized_keys
@@ -1589,9 +1592,6 @@
 #
 # @reset: ignore the existing content, set it with the given keys only
 #
-# Append public keys to user .ssh/authorized_keys on Unix systems (not
-# implemented for other systems).
-#
 # Returns: Nothing on success.
 #
 # Since: 5.2
@@ -1603,15 +1603,15 @@
 ##
 # @guest-ssh-remove-authorized-keys:
 #
+# Remove public keys from the user .ssh/authorized_keys on Unix
+# systems (not implemented for other systems). It's not an error if
+# the key is already missing.
+#
 # @username: the user account to remove the authorized keys
 #
 # @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys
 #     format)
 #
-# Remove public keys from the user .ssh/authorized_keys on Unix
-# systems (not implemented for other systems). It's not an error if
-# the key is already missing.
-#
 # Returns: Nothing on success.
 #
 # Since: 5.2
-- 
2.43.0

Re: [PULL 0/5] QAPI patches patches for 2024-02-03

[Peter Maydell]

On Sat, 3 Feb 2024 at 08:34, Markus Armbruster <armbru@redhat.com> wrote:
>
> The following changes since commit 29b008927ef6e3fbb70e6607b25d3fcae26a5190:
>
>   Merge tag 'pull-nic-config-2-20240202' of git://git.infradead.org/users/dwmw2/qemu into staging (2024-02-02 16:47:36 +0000)
>
> are available in the Git repository at:
>
>   https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-02-03
>
> for you to fetch changes up to 3424ed6caf9759eb57405d965537fd5f3d70026b:
>
>   qga/qapi-schema: Move command description right after command name (2024-02-03 09:20:33 +0100)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2024-02-03
>
> ----------------------------------------------------------------
> Markus Armbruster (5):
>       qapi: Drop redundant documentation of inherited members
>       qapi: Drop redundant documentation of conditional
>       qapi: Elide "Potential additional modes" from generated docs
>       qga: Move type description right after type name
>       qga/qapi-schema: Move command description right after command name


Applied, thanks.

Please update the changelog at https://wiki.qemu.org/ChangeLog/9.0
for any user-visible changes.

-- PMM