@@ -10,11 +10,10 @@
# = Audio
##
-##
-# @AudiodevPerDirectionOptions:
-#
# General audio backend options that are used for both playback and
# recording.
+##
+# @AudiodevPerDirectionOptions:
#
# @mixing-engine: use QEMU's mixing engine to mix all streams inside
# QEMU and convert audio formats when not supported by the
@@ -267,10 +267,9 @@
'file': 'ImageInfoSpecificFileWrapper'
} }
-##
-# @BlockNodeInfo:
-#
# Information about a QEMU image file
+##
+# @BlockNodeInfo:
#
# @filename: name of the image file
#
@@ -1494,8 +1493,6 @@
##
# @BlockdevSnapshotSync:
#
-# Either @device or @node-name must be set but not both.
-#
# @device: the name of the device to take a snapshot of.
#
# @node-name: graph node name to generate the snapshot from (Since
@@ -1512,6 +1509,9 @@
#
# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
+#
+# Note: Either @device or @node-name must be set but not both.
+#
##
{ 'struct': 'BlockdevSnapshotSync',
'data': { '*device': 'str', '*node-name': 'str',
@@ -2139,10 +2139,9 @@
'data': 'DriveMirror',
'allow-preconfig': true }
-##
-# @DriveMirror:
-#
# A set of parameters describing drive mirror setup.
+##
+# @DriveMirror:
#
# @job-id: identifier for the newly-created block job. If omitted,
# the device name will be used. (Since 2.7)
@@ -2553,10 +2552,9 @@
'*auto-finalize': 'bool', '*auto-dismiss': 'bool' },
'allow-preconfig': true }
-##
-# @BlockIOThrottle:
-#
# A set of parameters describing block throttling.
+##
+# @BlockIOThrottle:
#
# @device: Block device name
#
@@ -3073,10 +3071,9 @@
{ 'struct': 'BlockJobChangeOptionsMirror',
'data': { 'copy-mode' : 'MirrorCopyMode' } }
-##
-# @BlockJobChangeOptions:
-#
# Block job options that can be changed after job creation.
+##
+# @BlockJobChangeOptions:
#
# @id: The job identifier
#
@@ -3332,11 +3329,10 @@
'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool',
'*label': 'str', '*rw': 'bool' } }
-##
-# @BlockdevOptionsGenericFormat:
-#
# Driver specific block device options for image format that have no
# option besides their data source.
+##
+# @BlockdevOptionsGenericFormat:
#
# @file: reference to or definition of the data source block device
#
@@ -3363,11 +3359,10 @@
'data': { '*key-secret': 'str',
'*header': 'BlockdevRef'} }
-##
-# @BlockdevOptionsGenericCOWFormat:
-#
# Driver specific block device options for image format that have no
# option besides their data source and an optional backing file.
+##
+# @BlockdevOptionsGenericCOWFormat:
#
# @backing: reference to or definition of the backing file block
# device, null disables the backing file entirely. Defaults to
@@ -4385,11 +4380,10 @@
'*page-cache-size': 'int',
'*debug': 'int' } }
-##
-# @BlockdevOptionsCurlBase:
-#
# Driver specific block device options shared by all protocols
# supported by the curl backend.
+##
+# @BlockdevOptionsCurlBase:
#
# @url: URL of the image file
#
@@ -4645,11 +4639,10 @@
'data': { 'target': 'BlockdevRef', '*bitmap': 'BlockDirtyBitmap',
'*on-cbw-error': 'OnCbwError', '*cbw-timeout': 'uint32' } }
-##
-# @BlockdevOptions:
-#
# Options for creating a block device. Many options are available for
-# all block devices, independent of the block driver:
+# all block devices, independent of the block driver.
+##
+# @BlockdevOptions:
#
# @driver: block driver name
#
@@ -77,11 +77,10 @@
'*max-connections': 'uint32' },
'allow-preconfig': true }
-##
-# @BlockExportOptionsNbdBase:
-#
# An NBD block export (common options shared between nbd-server-add
# and the NBD branch of block-export-add).
+##
+# @BlockExportOptionsNbdBase:
#
# @name: Export name. If unspecified, the @device parameter is used
# as the export name. (Since 2.12)
@@ -213,10 +212,9 @@
'*logical-block-size': 'size',
'*serial': 'str' } }
-##
-# @NbdServerAddOptions:
-#
# An NBD block export, per legacy nbd-server-add command.
+##
+# @NbdServerAddOptions:
#
# @device: The device name or node name of the node to be exported
#
@@ -189,10 +189,9 @@
'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
'returns': 'str' }
-##
-# @ChardevCommon:
-#
# Configuration shared across all chardev backends
+##
+# @ChardevCommon:
#
# @logfile: The name of a logfile to save output
#
@@ -163,10 +163,9 @@
# 'prefix': 'QCRYPTO_BLOCK_FORMAT',
'data': ['qcow', 'luks']}
-##
-# @QCryptoBlockOptionsBase:
-#
# The common options that apply to all full disk encryption formats
+##
+# @QCryptoBlockOptionsBase:
#
# @format: the encryption format
#
@@ -175,10 +174,9 @@
{ 'struct': 'QCryptoBlockOptionsBase',
'data': { 'format': 'QCryptoBlockFormat' }}
-##
-# @QCryptoBlockOptionsQCow:
-#
# The options that apply to QCow/QCow2 AES-CBC encryption format
+##
+# @QCryptoBlockOptionsQCow:
#
# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
@@ -189,11 +187,10 @@
{ 'struct': 'QCryptoBlockOptionsQCow',
'data': { '*key-secret': 'str' }}
+# The options that apply to LUKS encryption format:
##
# @QCryptoBlockOptionsLUKS:
#
-# The options that apply to LUKS encryption format
-#
# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
# metadata only.
@@ -203,10 +200,9 @@
{ 'struct': 'QCryptoBlockOptionsLUKS',
'data': { '*key-secret': 'str' }}
-##
-# @QCryptoBlockCreateOptionsLUKS:
-#
# The options that apply to LUKS encryption format initialization
+##
+# @QCryptoBlockCreateOptionsLUKS:
#
# @cipher-alg: the cipher algorithm for data encryption Currently
# defaults to 'aes-256'.
@@ -268,11 +264,10 @@
'data': { 'qcow': 'QCryptoBlockOptionsQCow',
'luks': 'QCryptoBlockCreateOptionsLUKS' } }
-##
-# @QCryptoBlockInfoBase:
-#
# The common information that applies to all full disk encryption
# formats
+##
+# @QCryptoBlockInfoBase:
#
# @format: the encryption format
#
@@ -424,10 +419,9 @@
'data': {
'luks': 'QCryptoBlockAmendOptionsLUKS' } }
-##
-# @SecretCommonProperties:
-#
# Properties for objects of classes derived from secret-common.
+##
+# @SecretCommonProperties:
#
# @loaded: if true, the secret is loaded immediately when applying
# this option and will probably fail when processing the next
@@ -490,10 +484,9 @@
'base': 'SecretCommonProperties',
'data': { 'serial': 'int32' } }
-##
-# @TlsCredsProperties:
-#
# Properties for objects of classes derived from tls-creds.
+##
+# @TlsCredsProperties:
#
# @verify-peer: if true the peer credentials will be verified once the
# handshake is completed. This is a no-op for anonymous
@@ -497,10 +497,9 @@
{ 'enum': 'NumaOptionsType',
'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] }
-##
-# @NumaOptions:
-#
# A discriminated record of NUMA options. (for OptsVisitor)
+##
+# @NumaOptions:
#
# @type: NUMA option type
#
@@ -1198,10 +1197,9 @@
{ 'event': 'BALLOON_CHANGE',
'data': { 'actual': 'int' } }
-##
-# @HvBalloonInfo:
-#
# hv-balloon guest-provided memory status information.
+##
+# @HvBalloonInfo:
#
# @committed: the amount of memory in use inside the guest plus the
# amount of the memory unusable inside the guest (ballooned out,
@@ -722,10 +722,9 @@
{ 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' },
{ 'name': 'vmnet-bridged', 'if': 'CONFIG_VMNET' }] }
-##
-# @Netdev:
-#
# Captures the configuration of a network device.
+##
+# @Netdev:
#
# @id: identifier for monitor commands.
#
@@ -894,8 +893,6 @@
##
# @AnnounceParameters:
#
-# Parameters for self-announce timers
-#
# @initial: Initial delay (in ms) before sending the first GARP/RARP
# announcement
#
@@ -272,11 +272,10 @@
'*max_queue_size': 'uint32',
'*vnet_hdr_support': 'bool' } }
-##
-# @CryptodevBackendProperties:
-#
# Properties for cryptodev-backend and cryptodev-backend-builtin
# objects.
+##
+# @CryptodevBackendProperties:
#
# @queues: the number of queues for the cryptodev backend. Ignored
# for cryptodev-backend and must be 1 for
@@ -338,10 +337,9 @@
{ 'enum': 'NetfilterInsert',
'data': [ 'before', 'behind' ] }
-##
-# @NetfilterProperties:
-#
# Properties for objects of classes derived from netfilter.
+##
+# @NetfilterProperties:
#
# @netdev: id of the network device backend to filter
#
@@ -516,10 +514,9 @@
'*repeat': 'bool',
'*grab-toggle': 'GrabToggleKeys' } }
-##
-# @EventLoopBaseProperties:
-#
# Common properties for event loops
+##
+# @EventLoopBaseProperties:
#
# @aio-max-batch: maximum number of requests in a batch for the AIO
# engine, 0 means that the engine will use its default.
@@ -576,10 +573,9 @@
'base': 'EventLoopBaseProperties',
'data': {} }
-##
-# @MemoryBackendProperties:
-#
# Properties for objects of classes derived from memory-backend.
+##
+# @MemoryBackendProperties:
#
# @merge: if true, mark the memory as mergeable (default depends on
# the machine type)
@@ -826,10 +822,9 @@
'data': { 'pci-dev': 'str',
'node': 'uint32' } }
-##
-# @RngProperties:
-#
# Properties for objects of classes derived from rng.
+##
+# @RngProperties:
#
# @opened: if true, the device is opened immediately when applying
# this option and will probably fail when processing the next
@@ -1008,10 +1003,9 @@
{ 'name': 'x-vfio-user-server', 'features': [ 'unstable' ] }
] }
-##
-# @ObjectOptions:
-#
# Describes the options of a user creatable QOM object.
+##
+# @ObjectOptions:
#
# @qom-type: the class name for the object to be created
#
@@ -39,8 +39,6 @@
##
# @SetPasswordOptions:
#
-# Options for set_password.
-#
# @protocol:
# - 'vnc' to modify the VNC server password
# - 'spice' to modify the Spice server password
@@ -94,8 +92,6 @@
##
# @ExpirePasswordOptions:
#
-# General options for expire_password.
-#
# @protocol:
# - 'vnc' to modify the VNC server expiration
# - 'spice' to modify the Spice server expiration
@@ -206,8 +202,6 @@
##
# @SpiceBasicInfo:
#
-# The basic information for SPICE network connection
-#
# @host: IP address
#
# @port: port number
@@ -469,8 +463,6 @@
##
# @VncBasicInfo:
#
-# The basic information for vnc network connection
-#
# @host: IP address
#
# @service: The service name of the vnc port. This may depend on the
@@ -1598,8 +1590,6 @@
##
# @DisplayReloadOptions:
#
-# Options of the display configuration reload.
-#
# @type: Specify the display type.
#
# Since: 6.0
@@ -1641,8 +1631,6 @@
##
# @DisplayUpdateOptionsVNC:
#
-# Specify the VNC reload options.
-#
# @addresses: If specified, change set of addresses to listen for
# connections. Addresses configured for websockets are not
# touched.
@@ -1655,8 +1643,6 @@
##
# @DisplayUpdateOptions:
#
-# Options of the display configuration reload.
-#
# @type: Specify the display type.
#
# Since: 7.1
This is part of a project to overhaul the QMP reference manual. One goal of this overhaul is to "inline" inherited argument sections into command reference sections. A consequence of this design decision is that inherited doc block sections need to be merged with the inheritor's sections. When documentation is written for types whose primary purpose is to be inherited by other types, we need to know how to merge those paragraphs into the descendent. Much of the time, these paragraphs aren't actually useful to end users. Either remove information that's of little to no use to *either* audience, and convert what's left to garden-variety comments to prevent it from showing up in rendered documentation. Signed-off-by: John Snow <jsnow@redhat.com> --- qapi/audio.json | 5 ++--- qapi/block-core.json | 47 ++++++++++++++++++------------------------ qapi/block-export.json | 10 ++++----- qapi/char.json | 5 ++--- qapi/crypto.json | 33 ++++++++++++----------------- qapi/machine.json | 10 ++++----- qapi/net.json | 7 ++----- qapi/qom.json | 30 +++++++++++---------------- qapi/ui.json | 14 ------------- 9 files changed, 59 insertions(+), 102 deletions(-)