[PATCH 0/2] qapi: Minor documentation cleanups

[PATCH 0/2] qapi: Minor documentation cleanups

[Markus Armbruster]

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(-)

-- 
2.49.0

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

[Markus Armbruster]

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

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

[Markus Armbruster]

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

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

[Daniel P. Berrangé]

On Tue, Jul 08, 2025 at 09:28:27AM +0200, Markus Armbruster wrote:
> 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(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: 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 :|

Re: [PATCH 2/2] qapi: Clean up a few Errors: sections

[Daniel P. Berrangé]

On Tue, Jul 08, 2025 at 09:28:28AM +0200, Markus Armbruster wrote:
> 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(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: 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 :|

Re: [PATCH 0/2] qapi: Minor documentation cleanups

[Markus Armbruster]

Queued for 10.1.  Thanks for the review!