Skip to contentSkip to conversation

qmp: Documentation cleanups

PATCH In review Markus Armbruster 3 participants 11 messages Jan 29, 2024

lore
Share & tools
lore
#0 lore raw

cover qmp: Documentation cleanups

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(-)
Signature · 1 line
2.43.0
#1 lore raw

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

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.

---
 qapi/block-core.json | 2 --
 qapi/introspect.json | 2 --
 2 files changed, 4 deletions(-)
qapi/block-core.json +0 -2
index 48c181e55d..530c4af50f 100644
@@ -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',
qapi/introspect.json +0 -2
index 8df1ce85ed..b041b02ba8 100644
@@ -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',
Signature · 1 line
2.43.0
Reviewed-by on v1 1/5
#2 lore raw

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

Quoted 17 lines · 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

Quoted 7 lines

Remaining options are determined by the block driver.

---
 qapi/block-core.json | 2 --
 qapi/introspect.json | 2 --
 2 files changed, 4 deletions(-)
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org
#3 lore raw

PATCH 2/5 qapi: Drop redundant documentation of conditional

In reply to 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.

---
 qapi/misc-target.json | 2 --
 1 file changed, 2 deletions(-)
qapi/misc-target.json +0 -2
index 9195e7d26b..03e83c053f 100644
@@ -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:
Signature · 1 line
2.43.0
Reviewed-by on v1 2/5
#4 lore raw

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

Quoted 11 lines · Markus Armbruster

Documentation generated for dump-skeys contains

This command is only supported on s390 architecture.

and

    If
    ~~

    "TARGET_S390X"
Quoted 8 lines

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

---
 qapi/misc-target.json | 2 --
 1 file changed, 2 deletions(-)
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org
#5 lore raw

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

In reply to 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.

---
 qapi/block-export.json | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
qapi/block-export.json +6 -5
index 7874a49ba7..e063e9255a 100644
@@ -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
 ##
Signature · 1 line
2.43.0
Reviewed-by on v1 3/5
#6 lore raw

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

Quoted 19 lines · 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.

Quoted 4 lines
---
 qapi/block-export.json | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)
Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org
#7 lore raw

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

In reply to 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.

---
 qapi/block-core.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qapi/block-core.json +2 -2
index 530c4af50f..781c9bd03e 100644
@@ -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',
Signature · 1 line
2.43.0
Reviewed-by on v1 4/5
#8 lore raw

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

Quoted 35 lines · 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.

---
 qapi/block-core.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
qapi/block-core.json +2 -3
index 530c4af50f..781c9bd03e 100644
@@ -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

#9 lore raw

PATCH 5/5 qga/qapi-schema: Move command description right after command name

In reply to 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.

---
 qga/qapi-schema.json | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
qga/qapi-schema.json +9 -9
index 876e2a8ea8..50b0a558c7 100644
@@ -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
Signature · 1 line
2.43.0
Reviewed-by on v1 5/5
#10 lore raw

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

Quoted 72 lines · 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.

---
 qga/qapi-schema.json | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)
qga/qapi-schema.json +9 -10
index 876e2a8ea8..50b0a558c7 100644
@@ -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