qapi: Reformat doc comments to conform to current conventions

Change

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the reflown
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]

1 files changed, 29 insertions, 38 deletions

diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index bf04042f45..88291453ba 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -5,10 +5,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.
+# 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.
 #
 # Since: 2.1
 #
@@ -16,7 +15,6 @@
 #
 # -> { "execute": "rtc-reset-reinjection" }
 # <- { "return": {} }
-#
 ##
 { 'command': 'rtc-reset-reinjection',
   'if': 'TARGET_I386' }
@@ -28,17 +26,19 @@
 #
 # @uninit: The guest is uninitialized.
 #
-# @launch-update: The guest is currently being launched; plaintext data and
-#                 register state is being imported.
+# @launch-update: The guest is currently being launched; plaintext
+#     data and register state is being imported.
 #
-# @launch-secret: The guest is currently being launched; ciphertext data
-#                 is being imported.
+# @launch-secret: The guest is currently being launched; ciphertext
+#     data is being imported.
 #
 # @running: The guest is fully launched or migrated in.
 #
-# @send-update: The guest is currently being migrated out to another machine.
+# @send-update: The guest is currently being migrated out to another
+#     machine.
 #
-# @receive-update: The guest is currently being migrated from another machine.
+# @receive-update: The guest is currently being migrated from another
+#     machine.
 #
 # Since: 2.12
 ##
@@ -95,7 +95,6 @@
 # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
 #                  "build-id" : 0, "policy" : 0, "state" : "running",
 #                  "handle" : 1 } }
-#
 ##
 { 'command': 'query-sev', 'returns': 'SevInfo',
   'if': 'TARGET_I386' }
@@ -125,7 +124,6 @@
 #
 # -> { "execute": "query-sev-launch-measure" }
 # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
-#
 ##
 { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo',
   'if': 'TARGET_I386' }
@@ -133,8 +131,8 @@
 ##
 # @SevCapability:
 #
-# The struct describes capability for a Secure Encrypted Virtualization
-# feature.
+# The struct describes capability for a Secure Encrypted
+# Virtualization feature.
 #
 # @pdh: Platform Diffie-Hellman key (base64 encoded)
 #
@@ -144,8 +142,8 @@
 #
 # @cbitpos: C-bit location in page table entry
 #
-# @reduced-phys-bits: Number of physical Address bit reduction when SEV is
-#                     enabled
+# @reduced-phys-bits: Number of physical Address bit reduction when
+#     SEV is enabled
 #
 # Since: 2.12
 ##
@@ -160,8 +158,8 @@
 ##
 # @query-sev-capabilities:
 #
-# This command is used to get the SEV capabilities, and is supported on AMD
-# X86 platforms only.
+# This command is used to get the SEV capabilities, and is supported
+# on AMD X86 platforms only.
 #
 # Returns: SevCapability objects.
 #
@@ -173,7 +171,6 @@
 # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
 #                  "cpu0-id": "2lvmGwo+...61iEinw==",
 #                  "cbitpos": 47, "reduced-phys-bits": 1}}
-#
 ##
 { 'command': 'query-sev-capabilities', 'returns': 'SevCapability',
   'if': 'TARGET_I386' }
@@ -216,7 +213,7 @@
 # supported on AMD X86 platforms only.
 #
 # @mnonce: a random 16 bytes value encoded in base64 (it will be
-#          included in report)
+#     included in report)
 #
 # Returns: SevAttestationReport objects.
 #
@@ -227,7 +224,6 @@
 # -> { "execute" : "query-sev-attestation-report",
 #                  "arguments": { "mnonce": "aaaaaaa" } }
 # <- { "return" : { "data": "aaaaaaaabbbddddd"} }
-#
 ##
 { 'command': 'query-sev-attestation-report',
   'data': { 'mnonce': 'str' },
@@ -250,7 +246,6 @@
 # -> { "execute": "dump-skeys",
 #      "arguments": { "filename": "/tmp/skeys" } }
 # <- { "return": {} }
-#
 ##
 { 'command': 'dump-skeys',
   'data': { 'filename': 'str' },
@@ -260,18 +255,18 @@
 # @GICCapability:
 #
 # The struct describes capability for a specific GIC (Generic
-# Interrupt Controller) version. These bits are not only decided by
-# QEMU/KVM software version, but also decided by the hardware that
-# the program is running upon.
+# Interrupt Controller) version.  These bits are not only decided by
+# QEMU/KVM software version, but also decided by the hardware that the
+# program is running upon.
 #
-# @version: version of GIC to be described. Currently, only 2 and 3
-#           are supported.
+# @version: version of GIC to be described.  Currently, only 2 and 3
+#     are supported.
 #
 # @emulated: whether current QEMU/hardware supports emulated GIC
-#            device in user space.
+#     device in user space.
 #
-# @kernel: whether current QEMU/hardware supports hardware
-#          accelerated GIC device in kernel.
+# @kernel: whether current QEMU/hardware supports hardware accelerated
+#     GIC device in kernel.
 #
 # Since: 2.6
 ##
@@ -284,7 +279,7 @@
 ##
 # @query-gic-capabilities:
 #
-# This command is ARM-only. It will return a list of GICCapability
+# This command is ARM-only.  It will return a list of GICCapability
 # objects that describe its capability bits.
 #
 # Returns: a list of GICCapability objects.
@@ -296,7 +291,6 @@
 # -> { "execute": "query-gic-capabilities" }
 # <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
 #                 { "version": 3, "emulated": false, "kernel": true } ] }
-#
 ##
 { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'],
   'if': 'TARGET_ARM' }
@@ -357,7 +351,6 @@
 #                  "flc": true,
 #                  "sections": [{"node": 0, "size": 67108864},
 #                  {"node": 1, "size": 29360128}]} }
-#
 ##
 { 'command': 'query-sgx', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
 
@@ -377,7 +370,6 @@
 #                  "flc": true,
 #                  "section" : [{"node": 0, "size": 67108864},
 #                  {"node": 1, "size": 29360128}]} }
-#
 ##
 { 'command': 'query-sgx-capabilities', 'returns': 'SGXInfo', 'if': 'TARGET_I386' }
 
@@ -470,7 +462,6 @@
 #         }
 #      ]
 #    }
-#
 ##
 { 'command': 'xen-event-list',
   'returns': ['EvtchnInfo'],
@@ -483,7 +474,8 @@
 #
 # @port: The port number
 #
-# Returns: - Nothing on success.
+# Returns:
+# - Nothing on success.
 #
 # Since: 8.0
 #
@@ -491,7 +483,6 @@
 #
 # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
 # <- { "return": { } }
-#
 ##
 { 'command': 'xen-event-inject',
   'data': { 'port': 'uint32' },