qapi: Minor documentation cleanups
cover qapi: Minor documentation cleanups
Markus Armbruster (2):
qapi: Clean up "This command will do ..." command descriptions
qapi: Clean up a few Errors: sections
qapi/control.json | 9 +++++---- qapi/misc-i386.json | 18 ++++++++---------- qapi/qom.json | 14 ++++++-------- 3 files changed, 19 insertions(+), 22 deletions(-)
Signature · 1 line
2.49.0
PATCH 1/2 qapi: Clean up "This command will do ..." command descriptions
Use imperative mood "Do ..." instead.
Signed-off-by Markus Armbruster <[email protected]>
--- qapi/control.json | 9 +++++---- qapi/misc-i386.json | 11 +++++------ qapi/qom.json | 10 ++++------ 3 files changed, 14 insertions(+), 16 deletions(-)
qapi/control.json +5 -4
@@ -158,10 +158,11 @@ ## # @quit: # -# This command will cause the QEMU process to exit gracefully. While -# every attempt is made to send the QMP response before terminating, -# this is not guaranteed. When using this interface, a premature EOF -# would not be unexpected. +# Request graceful QEMU process termination. +# +# While every attempt is made to send the QMP response before +# terminating, this is not guaranteed. When using this interface, a +# premature EOF would not be unexpected. # # Since: 0.14 #
qapi/misc-i386.json +5 -6
@@ -6,9 +6,9 @@ ## # @rtc-reset-reinjection: # -# This command will reset the RTC interrupt reinjection backlog. Can -# be used if another mechanism to synchronize guest time is in effect, -# for example QEMU guest agent's guest-set-time command. +# Reset the RTC interrupt reinjection backlog. Can be used if another +# mechanism to synchronize guest time is in effect, for example QEMU +# guest agent's guest-set-time command. # # Use of this command is only applicable for x86 machines with an RTC, # and on other machines will silently return without performing any
@@ -233,8 +233,7 @@ ## # @sev-inject-launch-secret: # -# This command injects a secret blob into memory of a SEV/SEV-ES -# guest. +# Inject a secret blob into a SEV/SEV-ES guest's memory. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. SEV-SNP guests do
@@ -272,7 +271,7 @@ ## # @query-sev-attestation-report: # -# This command is used to get the SEV attestation report. +# Get the SEV attestation report. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. The attestation
qapi/qom.json +4 -6
@@ -48,8 +48,7 @@ ## # @qom-list: # -# This command will list any properties of a object given a path in -# the object model. +# List properties of a object given a path in the object model. # # @path: the path within the object model. See @qom-get for a # description of this parameter.
@@ -76,8 +75,7 @@ ## # @qom-get: # -# This command will get a property from a object model path and return -# the value. +# Get a property value. # # @path: The path within the object model. There are two forms of # supported paths--absolute and partial paths.
@@ -128,7 +126,7 @@ ## # @qom-set: # -# This command will set a property from a object model path. +# Set a property value. # # @path: see @qom-get for a description of this parameter #
@@ -171,7 +169,7 @@ ## # @qom-list-types: # -# This command will return a list of types given search parameters +# Return a list of types given search parameters. # # @implements: if specified, only return types that implement this # type name
Signature · 1 line
2.49.0
Re: [PATCH 1/2] qapi: Clean up "This command will do ..." command descriptions
Quoted 8 lines · Markus Armbruster
Use imperative mood "Do ..." instead.
Signed-off-by Markus Armbruster <[email protected]>--- qapi/control.json | 9 +++++---- qapi/misc-i386.json | 11 +++++------ qapi/qom.json | 10 ++++------ 3 files changed, 14 insertions(+), 16 deletions(-)
Reviewed-by Daniel P. Berrangé <[email protected]>
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
PATCH 2/2 qapi: Clean up a few Errors: sections
In reply to Markus ArmbrusterUse the conventional "- If <error-condition>" phrasing, optionally with ", <error-class>".
Signed-off-by Markus Armbruster <[email protected]>
--- qapi/misc-i386.json | 7 +++---- qapi/qom.json | 4 ++-- 2 files changed, 5 insertions(+), 6 deletions(-)
qapi/misc-i386.json +3 -4
@@ -283,10 +283,9 @@ # Returns: SevAttestationReport objects. # # Errors: -# - This will return an error if the attestation report is -# unavailable, either due to an invalid guest configuration -# or if the guest has not reached the required SEV state, -# GenericError +# - If the attestation report is unavailable, either due to an +# invalid guest configuration or because the guest has not +# reached the required SEV state, GenericError # # Since: 6.1 #
qapi/qom.json +2 -2
@@ -1259,7 +1259,7 @@ # Create a QOM object. # # Errors: -# - Error if @qom-type is not a valid class name +# - If @qom-type is not a valid class name # # Since: 2.0 #
@@ -1281,7 +1281,7 @@ # @id: the name of the QOM object to remove # # Errors: -# - Error if @id is not a valid id for a QOM object +# - If @id is not a valid id for a QOM object # # Since: 2.0 #
Signature · 1 line
2.49.0
Re: [PATCH 2/2] qapi: Clean up a few Errors: sections
Quoted 8 lines · Markus Armbruster
Use the conventional "- If <error-condition>" phrasing, optionally with ", <error-class>".
Signed-off-by Markus Armbruster <[email protected]>--- qapi/misc-i386.json | 7 +++---- qapi/qom.json | 4 ++-- 2 files changed, 5 insertions(+), 6 deletions(-)
Reviewed-by Daniel P. Berrangé <[email protected]>
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Markus Armbruster
AppliedQueued for 10.1. Thanks for the review!