Commit da575af1b8 for qemu.org
commit da575af1b8af5efcb412d1aa2e0c777f187bf700
Author: John Snow <jsnow@redhat.com>
Date: Mon Sep 28 15:25:53 2026 -0400
qapi: convert/split intros for commands
Convert or split apart the existing intro for any remaining commands
in the QAPI schema into introduction and details sections. The
introduction is indented, remaining plaintext/details paragraphs
are not.
For commands that have automatically generated documentation inserted
at parse time, these new split points serve as the new insertion
point. This affects the rendered documentation for `netdev_add`,
`query-stats`, and `query-gic-capabilities` in particular, whose
arguments descriptions / "Returns:" documentation are pushed upwards.
Minor rephrasings are applied for `query-qmp-schema` to help
the split flow better in rendered documentation.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260928192557.509157-7-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message corrected]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/control.json b/qapi/control.json
index 2788ce32e2..ef63a8a261 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -152,8 +152,7 @@
##
# @quit:
-#
-# Request graceful QEMU process termination.
+# 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
diff --git a/qapi/introspect.json b/qapi/introspect.json
index bd42aac335..d579e5c855 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -17,15 +17,15 @@
##
# @query-qmp-schema:
-#
-# Command `query-qmp-schema` exposes the QMP wire ABI as an array of
-# `SchemaInfo`. This lets QMP clients figure out what commands and
-# events are available in this QEMU, and their parameters and results.
-#
-# However, the `SchemaInfo` can't reflect all the rules and
-# restrictions that apply to QMP. It's interface introspection
-# (figuring out what's there), not interface specification. The
-# specification is in the QAPI schema.
+# Command `query-qmp-schema` exposes the QMP wire ABI as an array
+# of `SchemaInfo`. This lets QMP clients figure out what commands
+# and events are available in this QEMU, and their parameters and
+# results.
+#
+# The `SchemaInfo` can't reflect all the rules and restrictions that
+# apply to QMP. It's interface introspection (figuring out what's
+# there), not interface specification. The specification is in the
+# QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
# backwards-compatible across QEMU versions, the introspection output
diff --git a/qapi/machine.json b/qapi/machine.json
index b5d4eb8db9..e9584f9166 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -2007,13 +2007,13 @@
##
# @query-cpu-model-comparison:
+# Compares two CPU models, @modela and @modelb, returning how they
+# compare in a specific configuration.
#
-# Compares two CPU models, @modela and @modelb, returning how they
-# compare in a specific configuration. The results indicates how both
-# models compare regarding runnability. This result can be used by
-# tooling to make decisions if a certain CPU model will run in a
-# certain configuration or if a compatible CPU model has to be created
-# by baselining.
+# The results indicates how both models compare regarding runnability.
+# This result can be used by tooling to make decisions if a certain
+# CPU model will run in a certain configuration or if a compatible CPU
+# model has to be created by baselining.
#
# Usually, a CPU model is compared against the maximum possible CPU
# model of a certain configuration (e.g. the "host" model for KVM).
@@ -2063,11 +2063,10 @@
##
# @query-cpu-model-baseline:
-#
-# Baseline two CPU models, @modela and @modelb, creating a compatible
-# third model. The created model will always be a static,
-# migration-safe CPU model (see "static" CPU model expansion for
-# details).
+# Baseline two CPU models, @modela and @modelb, creating a
+# compatible third model. The created model will always be a
+# static, migration-safe CPU model (see "static" CPU model
+# expansion for details).
#
# This interface can be used by tooling to create a compatible CPU
# model out two CPU models. The created CPU model will be identical
@@ -2135,11 +2134,11 @@
##
# @query-cpu-model-expansion:
-#
-# Expands a given CPU model, @model, (or a combination of CPU model +
-# additional options) to different granularities, specified by @type,
-# allowing tooling to get an understanding what a specific CPU model
-# looks like in QEMU under a certain configuration.
+# Expands a given CPU model, @model, (or a combination of CPU
+# model + additional options) to different granularities,
+# specified by @type, allowing tooling to get an understanding
+# what a specific CPU model looks like in QEMU under a certain
+# configuration.
#
# This interface can be used to query the "host" CPU model.
#
diff --git a/qapi/migration.json b/qapi/migration.json
index f7f223f9ab..889a9b89c2 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1826,9 +1826,9 @@
##
# @calc-dirty-rate:
-#
-# Start measuring dirty page rate of the VM. Results can be retrieved
-# with `query-dirty-rate` after measurements are completed.
+# Start measuring dirty page rate of the VM. Results can be
+# retrieved with `query-dirty-rate` after measurements are
+# completed.
#
# Dirty page rate is the number of pages changed in a given time
# period expressed in MiB/s. The following methods of calculation are
@@ -1945,8 +1945,7 @@
##
# @set-vcpu-dirty-limit:
-#
-# Set the upper limit of dirty page rate for virtual CPUs.
+# Set the upper limit of dirty page rate for virtual CPUs.
#
# Requires KVM with accelerator property "dirty-ring-size" set. A
# virtual CPU's dirty page rate is a measure of its memory load. To
@@ -1971,8 +1970,7 @@
##
# @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
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index 8cb2ea7795..70859b2c37 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -28,9 +28,8 @@
##
# @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.
diff --git a/qapi/misc.json b/qapi/misc.json
index b62cabc2b7..4469e44d05 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -12,9 +12,8 @@
##
# @add_client:
-#
-# Allow client connections for VNC, Spice and socket based character
-# devices to be passed in to QEMU via SCM_RIGHTS.
+# Allow client connections for VNC, Spice and socket based
+# character devices to be passed in to QEMU via SCM_RIGHTS.
#
# If the FD associated with @fdname is not a socket, the command will
# fail and the FD will be closed.
@@ -185,8 +184,7 @@
##
# @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
diff --git a/qapi/net.json b/qapi/net.json
index 81d1ab1c2f..3541dd7cad 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -37,8 +37,7 @@
##
# @netdev_add:
-#
-# Add a network backend.
+# Add a network backend.
#
# Additional arguments depend on the type.
#
diff --git a/qapi/qdev.json b/qapi/qdev.json
index a35321d2fd..f390354d68 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -162,11 +162,10 @@
##
# @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
diff --git a/qapi/stats.json b/qapi/stats.json
index af57ec0854..e9d05390c3 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -175,9 +175,8 @@
##
# @query-stats:
-#
-# Return runtime-collected statistics for objects such as the VM or
-# its vCPUs.
+# Return runtime-collected statistics for objects such as the VM
+# or its vCPUs.
#
# The arguments are a `StatsFilter` and specify the provider and
# objects to return statistics about.
diff --git a/qapi/transaction.json b/qapi/transaction.json
index c0dc811ba6..daecf843c9 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -197,10 +197,9 @@
##
# @transaction:
-#
-# Executes a number of transactionable QMP commands atomically. If
-# any operation fails, then the entire set of actions will be
-# abandoned and the appropriate error returned.
+# Executes a number of transactionable QMP commands atomically.
+# If any operation fails, then the entire set of actions will be
+# abandoned and the appropriate error returned.
#
# For external snapshots, the dictionary contains the device, the file
# to use for the new snapshot, and the format. The default format, if
diff --git a/qapi/ui.json b/qapi/ui.json
index a59cd63577..73ee2cb205 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1198,8 +1198,7 @@
##
# @input-send-event:
-#
-# Send input event(s) to guest.
+# Send input event(s) to guest.
#
# The @device and @head parameters can be used to send the input event
# to specific input devices in case (a) multiple input devices of the