John Snow <[email protected]> writes: > 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 <[email protected]> > --- > 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.
'overlay' and 'node' refer to arguments, so they should be @overlay and @node. Since the arguments are in type BlockdevSnapshot, the reference is non-local until the inliner lands. We may want to render this paragraph below the argument descriptions to avoid forward references. This requires splitting it off the intro. We can do it now, or leave it for later. Not splitting now keeps the conversion simple, which is a plus. It reindents the entire unsplit intro, and if we do split it later, the part split off gets reindented right back. I'm leaning towards not rocking the boat, but you decide. Not noting these things again. > # > # Features: > # > @@ -2471,15 +2470,15 @@ > ## > # @block-dirty-bitmap-merge: > # Drop the blank line. > -# 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. This one arguably lacks an intro. Let's not worry about this now. > # > # @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 > # Shouldn't this one be in "[PATCH 5/9] qapi: split intro sections for commands"? > @@ -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: > # Drop the blank line. > -# 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 > #
