From 709c5a650e030d7e651e4a72ba42016b44da7f93 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 29 Jan 2024 12:50:04 +0100 Subject: [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. Signed-off-by: Markus Armbruster Message-ID: <20240129115008.674248-2-armbru@redhat.com> Reviewed-by: Eric Blake --- 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', From 763db74d2b61e34b0747a353c791d0ad6eb8ad2b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 29 Jan 2024 12:50:05 +0100 Subject: [PATCH 2/5] qapi: Drop redundant documentation of conditional 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 Message-ID: <20240129115008.674248-3-armbru@redhat.com> Reviewed-by: Eric Blake --- 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: From e3240ac5800f11d0a00262d76180d9a3227131fb Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 29 Jan 2024 12:50:06 +0100 Subject: [PATCH 3/5] qapi: Elide "Potential additional modes" from generated docs 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 Message-ID: <20240129115008.674248-4-armbru@redhat.com> Reviewed-by: Eric Blake --- 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 ## From d6a5ca3acfcbc164bbb15a0690d997212b29d6c3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 29 Jan 2024 12:50:07 +0100 Subject: [PATCH 4/5] qga: Move type description right after type name 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 Message-ID: <20240129115008.674248-5-armbru@redhat.com> Reviewed-by: Konstantin Kostiuk --- 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', From 3424ed6caf9759eb57405d965537fd5f3d70026b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 29 Jan 2024 12:50:08 +0100 Subject: [PATCH 5/5] qga/qapi-schema: Move command description right after command name 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 Message-ID: <20240129115008.674248-6-armbru@redhat.com> Reviewed-by: Konstantin Kostiuk --- 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