[PATCH 0/5] qmp: Documentation cleanups

[PATCH 0/5] qmp: Documentation cleanups

[Markus Armbruster]

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

[PATCH 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>
---
 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

[PATCH 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>
---
 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

[PATCH 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>
---
 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

[PATCH 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>
---
 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

[PATCH 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>
---
 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: [PATCH 5/5] qga/qapi-schema: Move command description right after command name

[Konstantin Kostiuk]

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

Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>

On Mon, Jan 29, 2024 at 1:50 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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>
> ---
>  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
>
>

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

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

[Konstantin Kostiuk]

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

Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com>

On Mon, Jan 29, 2024 at 1:50 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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>
> ---
>  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
>
>

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

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

[Eric Blake]

On Mon, Jan 29, 2024 at 12:50:06PM +0100, Markus Armbruster wrote:
> 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>
> ---
>  qapi/block-export.json | 11 ++++++-----
>  1 file changed, 6 insertions(+), 5 deletions(-)

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

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

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

[Eric Blake]

On Mon, Jan 29, 2024 at 12:50:04PM +0100, Markus Armbruster wrote:
> 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>
> ---
>  qapi/block-core.json | 2 --
>  qapi/introspect.json | 2 --
>  2 files changed, 4 deletions(-)

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

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

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

[Eric Blake]

On Mon, Jan 29, 2024 at 12:50:05PM +0100, Markus Armbruster wrote:
> 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>
> ---
>  qapi/misc-target.json | 2 --
>  1 file changed, 2 deletions(-)

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

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