* [PATCH 1/2] qapi: Clean up "This command will do ..." command descriptions
2025-07-08 7:28 [PATCH 0/2] qapi: Minor documentation cleanups Markus Armbruster
@ 2025-07-08 7:28 ` Markus Armbruster
2025-07-08 7:50 ` Daniel P. Berrangé
2025-07-08 7:28 ` [PATCH 2/2] qapi: Clean up a few Errors: sections Markus Armbruster
2025-07-11 17:35 ` [PATCH 0/2] qapi: Minor documentation cleanups Markus Armbruster
2 siblings, 1 reply; 6+ messages in thread
From: Markus Armbruster @ 2025-07-08 7:28 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, pbonzini, berrange, eduardo, steven.sistare
Use imperative mood "Do ..." instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/control.json | 9 +++++----
qapi/misc-i386.json | 11 +++++------
qapi/qom.json | 10 ++++------
3 files changed, 14 insertions(+), 16 deletions(-)
diff --git a/qapi/control.json b/qapi/control.json
index 34b733f63b..1bc4ac8734 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -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
#
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 5fefa0a484..b53ed39288 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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
diff --git a/qapi/qom.json b/qapi/qom.json
index b133b06447..9670d10246 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -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
--
2.49.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/2] qapi: Clean up a few Errors: sections
2025-07-08 7:28 [PATCH 0/2] qapi: Minor documentation cleanups Markus Armbruster
2025-07-08 7:28 ` [PATCH 1/2] qapi: Clean up "This command will do ..." command descriptions Markus Armbruster
@ 2025-07-08 7:28 ` Markus Armbruster
2025-07-08 7:51 ` Daniel P. Berrangé
2025-07-11 17:35 ` [PATCH 0/2] qapi: Minor documentation cleanups Markus Armbruster
2 siblings, 1 reply; 6+ messages in thread
From: Markus Armbruster @ 2025-07-08 7:28 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, pbonzini, berrange, eduardo, steven.sistare
Use the conventional "- If <error-condition>" phrasing, optionally
with ", <error-class>".
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/misc-i386.json | 7 +++----
qapi/qom.json | 4 ++--
2 files changed, 5 insertions(+), 6 deletions(-)
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index b53ed39288..24a2e143f6 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -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
#
diff --git a/qapi/qom.json b/qapi/qom.json
index 9670d10246..9020e12650 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -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
#
--
2.49.0
^ permalink raw reply related [flat|nested] 6+ messages in thread