qmp: Documentation cleanups
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
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
@@ -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
@@ -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
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.
Signed-off-by Markus Armbruster <[email protected]>--- 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
PATCH 2/5 qapi: Drop redundant documentation of conditional
In reply to Markus ArmbrusterDocumentation 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
@@ -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
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.Signed-off-by Markus Armbruster <[email protected]>--- 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
PATCH 3/5 qapi: Elide "Potential additional modes" from generated docs
In reply to Markus ArmbrusterDocumentation 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
@@ -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
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
Signed-off-by Markus Armbruster <[email protected]>--- 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
PATCH 4/5 qga: Move type description right after type name
In reply to Markus ArmbrusterDocumentation 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
@@ -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
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.
Signed-off-by Markus Armbruster <[email protected]>--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qapi/block-core.json +2
-3@@ -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
In reply to Markus ArmbrusterDocumentation 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
@@ -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
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.
Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-)qga/qapi-schema.json +9
-10@@ -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