[PATCH 2/9] qapi: convert multi-paragraph intros (commands)

[John Snow <jsnow@redhat.com>]

This patch converts some slightly-non-trivial intros with more than
one paragraph, but doesn't create any new intro/details splits.

Review notes: Some of these possibly could be split, but as they are commands
(not eligible as an inlining source) and the additional information in
the intro is not terribly long, I opted to leave them alone instead of
laboring on prose rewrites.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-core.json | 49 +++++++++++++++++++++-----------------------
 qapi/block.json      | 29 +++++++++++++-------------
 qapi/migration.json  |  9 ++++----
 qapi/misc-arm.json   |  9 ++++----
 qapi/misc.json       | 13 ++++++------
 qapi/qdev.json       | 14 ++++++-------
 6 files changed, 58 insertions(+), 65 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 1ca147285e7..c505369aeb2 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1772,13 +1772,12 @@
 
 ##
 # @blockdev-snapshot:
+#     Takes a snapshot of a block device.
 #
-# Takes a snapshot of a block device.
-#
-# Take a snapshot, by installing 'node' as the backing image of
-# 'overlay'.  Additionally, if 'node' is associated with a block
-# device, the block device changes to using 'overlay' as its new
-# active image.
+#     Take a snapshot, by installing 'node' as the backing image of
+#     'overlay'.  Additionally, if 'node' is associated with a block
+#     device, the block device changes to using 'overlay' as its new
+#     active image.
 #
 # Features:
 #
@@ -2471,15 +2470,15 @@
 ##
 # @block-dirty-bitmap-merge:
 #
-# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
-# Dirty bitmaps in @bitmaps will be unchanged, except if it also
-# appears as the @target bitmap.  Any bits already set in @target will
-# still be set after the merge, i.e., this operation does not clear
-# the target.  On error, @target is unchanged.
+#     Merge dirty bitmaps listed in @bitmaps to the @target dirty
+#     bitmap.  Dirty bitmaps in @bitmaps will be unchanged, except if
+#     it also appears as the @target bitmap.  Any bits already set in
+#     @target will still be set after the merge, i.e., this operation
+#     does not clear the target.  On error, @target is unchanged.
 #
-# The resulting bitmap will count as dirty any clusters that were
-# dirty in any of the source bitmaps.  This can be used to achieve
-# backup checkpoints, or in simpler usages, to copy bitmaps.
+#     The resulting bitmap will count as dirty any clusters that were
+#     dirty in any of the source bitmaps.  This can be used to achieve
+#     backup checkpoints, or in simpler usages, to copy bitmaps.
 #
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
@@ -5848,15 +5847,14 @@
 
 ##
 # @block-set-write-threshold:
+#     Change the write threshold for a block drive.  An event will be
+#     delivered if a write to this block drive crosses the configured
+#     threshold.  The threshold is an offset, thus must be
+#     non-negative.  Default is no write threshold.  Setting the
+#     threshold to zero disables it.
 #
-# Change the write threshold for a block drive.  An event will be
-# delivered if a write to this block drive crosses the configured
-# threshold.  The threshold is an offset, thus must be non-negative.
-# Default is no write threshold.  Setting the threshold to zero
-# disables it.
-#
-# This is useful to transparently resize thin-provisioned drives
-# without the guest OS noticing.
+#     This is useful to transparently resize thin-provisioned drives
+#     without the guest OS noticing.
 #
 # @node-name: graph node name on which the threshold must be set.
 #
@@ -5938,11 +5936,10 @@
 
 ##
 # @x-blockdev-set-iothread:
+#     Move @node and its children into the @iothread.  If @iothread is
+#     null then move @node and its children into the main loop.
 #
-# Move @node and its children into the @iothread.  If @iothread is
-# null then move @node and its children into the main loop.
-#
-# The node must not be attached to a BlockBackend.
+#     The node must not be attached to a BlockBackend.
 #
 # @node-name: the name of the block driver node
 #
diff --git a/qapi/block.json b/qapi/block.json
index e47592d5500..15f08372564 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -181,12 +181,13 @@
 
 ##
 # @blockdev-close-tray:
+#     Closes a block device's tray.
 #
-# Closes a block device's tray.  If there is a block driver state tree
-# associated with the block device (which is currently ejected), that
-# tree will be loaded as the medium.
+#     If there is a block driver state tree associated with the block
+#     device (which is currently ejected), that tree will be loaded as
+#     the medium.
 #
-# If the tray was already closed before, this will be a no-op.
+#     If the tray was already closed before, this will be a no-op.
 #
 # @device: Block device name
 #
@@ -218,13 +219,12 @@
 
 ##
 # @blockdev-remove-medium:
+#     Removes a medium (a block driver state tree) from a block
+#     device.  That block device's tray must currently be open
+#     (unless there is no attached guest device).
 #
-# Removes a medium (a block driver state tree) from a block device.
-# That block device's tray must currently be open (unless there is no
-# attached guest device).
-#
-# If the tray is open and there is no medium inserted, this will be a
-# no-op.
+#     If the tray is open and there is no medium inserted, this will
+#     be a no-op.
 #
 # @id: The name or QOM path of the guest device
 #
@@ -504,12 +504,11 @@
 
 ##
 # @block-latency-histogram-set:
+#     Manage read, write and flush latency histograms for the device.
 #
-# Manage read, write and flush latency histograms for the device.
-#
-# If only @id parameter is specified, remove all present latency
-# histograms for the device.  Otherwise, add/reset some of (or all)
-# latency histograms.
+#     If only @id parameter is specified, remove all present latency
+#     histograms for the device.  Otherwise, add/reset some of (or
+#     all) latency histograms.
 #
 # @id: The name or QOM path of the guest device.
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 8096ef64682..13c446b922f 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1965,12 +1965,11 @@
 
 ##
 # @cancel-vcpu-dirty-limit:
+#     Cancel the upper limit of dirty page rate for virtual CPUs.
 #
-# Cancel the upper limit of dirty page rate for virtual CPUs.
-#
-# Cancel the dirty page limit for the vCPU which has been set with
-# `set-vcpu-dirty-limit` command.  Note that this command requires
-# support from dirty ring, same as the `set-vcpu-dirty-limit`.
+#     Cancel the dirty page limit for the vCPU which has been set with
+#     `set-vcpu-dirty-limit` command.  Note that this command requires
+#     support from dirty ring, same as the `set-vcpu-dirty-limit`.
 #
 # @cpu-index: index of a virtual CPU, default is all.
 #
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index 8cb2ea77951..64059b5688d 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -28,12 +28,11 @@
 
 ##
 # @query-gic-capabilities:
+#     It will return a list of `GICCapability` objects that describe
+#     its capability bits.
 #
-# It will return a list of `GICCapability` objects that describe its
-# capability bits.
-#
-# On non-ARM targets this command will report an error as the GIC
-# technology is not applicable.
+#     On non-ARM targets this command will report an error as the GIC
+#     technology is not applicable.
 #
 # Since: 2.6
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index b3c2a1421f3..374711ac6c7 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -178,14 +178,13 @@
 
 ##
 # @x-exit-preconfig:
+#     Exit from "preconfig" state
 #
-# Exit from "preconfig" state
-#
-# This command makes QEMU exit the preconfig state and proceed with VM
-# initialization using configuration data provided on the command line
-# and via the QMP monitor during the preconfig state.  The command is
-# only available during the preconfig state (i.e. when the --preconfig
-# command line option was in use).
+#     This command makes QEMU exit the preconfig state and proceed
+#     with VM initialization using configuration data provided on the
+#     command line and via the QMP monitor during the preconfig state.
+#     The command is only available during the preconfig state
+#     (i.e. when the --preconfig command line option was in use).
 #
 # Features:
 #
diff --git a/qapi/qdev.json b/qapi/qdev.json
index a35321d2fd1..e19a92a44e8 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -163,14 +163,14 @@
 ##
 # @device-sync-config:
 #
-# Synchronize device configuration from host to guest part.  First,
-# copy the configuration from the host part (backend) to the guest
-# part (frontend).  Then notify guest software that device
-# configuration changed.
+#     Synchronize device configuration from host to guest part.
+#     First, copy the configuration from the host part (backend) to
+#     the guest part (frontend).  Then notify guest software that
+#     device configuration changed.
 #
-# The command may be used to notify the guest about block device
-# capacity change.  Currently only vhost-user-blk device supports
-# this.
+#     The command may be used to notify the guest about block device
+#     capacity change.  Currently only vhost-user-blk device supports
+#     this.
 #
 # @id: the device's ID or QOM path
 #
-- 
2.55.0