Skip to contentSkip to conversation

qapi: Minor documentation cleanups

PATCH Applied Markus Armbruster 2 participants 6 messages Jul 8, 2025 – Jul 11, 2025

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

PATCH 1/2 qapi: Clean up "This command will do ..." command descriptions

Use imperative mood "Do ..." instead.

---
 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
index 34b733f63b..1bc4ac8734 100644
@@ -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
index 5fefa0a484..b53ed39288 100644
@@ -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
index b133b06447..9670d10246 100644
@@ -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
Reviewed-by on v1 1/2
#2 lore raw

Re: [PATCH 1/2] qapi: Clean up "This command will do ..." command descriptions

Quoted 8 lines · Markus Armbruster

Use imperative mood "Do ..." instead.

---
 qapi/control.json   |  9 +++++----
 qapi/misc-i386.json | 11 +++++------
 qapi/qom.json       | 10 ++++------
 3 files changed, 14 insertions(+), 16 deletions(-)

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 :|
#3 lore raw

PATCH 2/2 qapi: Clean up a few Errors: sections

In reply to Markus Armbruster

Use the conventional "- If <error-condition>" phrasing, optionally with ", <error-class>".

---
 qapi/misc-i386.json | 7 +++----
 qapi/qom.json       | 4 ++--
 2 files changed, 5 insertions(+), 6 deletions(-)
qapi/misc-i386.json +3 -4
index b53ed39288..24a2e143f6 100644
@@ -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
index 9670d10246..9020e12650 100644
@@ -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
Reviewed-by on v1 2/2
#4 lore raw

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

---
 qapi/misc-i386.json | 7 +++----
 qapi/qom.json       | 4 ++--
 2 files changed, 5 insertions(+), 6 deletions(-)

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