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]
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 019d2d1..e6dcee7 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -16,7 +16,6 @@
# @name: Name of the VirtIODevice
#
# Since: 7.2
-#
##
{ 'struct': 'VirtioInfo',
'data': { 'path': 'str',
@@ -28,6 +27,7 @@
# Returns a list of all realized VirtIODevices
#
# Features:
+#
# @unstable: This command is meant for debugging.
#
# Returns: List of gathered VirtIODevices
@@ -60,9 +60,7 @@
# }
# ]
# }
-#
##
-
{ 'command': 'x-query-virtio',
'returns': [ 'VirtioInfo' ],
'features': [ 'unstable' ] }
@@ -70,7 +68,7 @@
##
# @VhostStatus:
#
-# Information about a vhost device. This information will only be
+# Information about a vhost device. This information will only be
# displayed if the vhost device is active.
#
# @n-mem-sections: vhost_dev n_mem_sections
@@ -98,9 +96,7 @@
# @log-size: vhost_dev log_size
#
# Since: 7.2
-#
##
-
{ 'struct': 'VhostStatus',
'data': { 'n-mem-sections': 'int',
'n-tmp-sections': 'int',
@@ -119,8 +115,8 @@
# @VirtioStatus:
#
# Full status of the virtio device with most VirtIODevice members.
-# Also includes the full status of the corresponding vhost device
-# if the vhost device is active.
+# Also includes the full status of the corresponding vhost device if
+# the vhost device is active.
#
# @name: VirtIODevice name
#
@@ -136,8 +132,8 @@
#
# @device-endian: VirtIODevice device_endian
#
-# @num-vqs: VirtIODevice virtqueue count. This is the number of active
-# virtqueues being used by the VirtIODevice.
+# @num-vqs: VirtIODevice virtqueue count. This is the number of
+# active virtqueues being used by the VirtIODevice.
#
# @status: VirtIODevice configuration status (VirtioDeviceStatus)
#
@@ -163,14 +159,12 @@
#
# @use-guest-notifier-mask: VirtIODevice use_guest_notifier_mask flag
#
-# @vhost-dev: Corresponding vhost device info for a given VirtIODevice.
-# Present if the given VirtIODevice has an active vhost
-# device.
+# @vhost-dev: Corresponding vhost device info for a given
+# VirtIODevice. Present if the given VirtIODevice has an active
+# vhost device.
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtioStatus',
'data': { 'name': 'str',
'device-id': 'uint16',
@@ -202,6 +196,7 @@
# @path: Canonical QOM path of the VirtIODevice
#
# Features:
+#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioStatus of the virtio device
@@ -433,9 +428,7 @@
# "use-started": true
# }
# }
-#
##
-
{ 'command': 'x-query-virtio-status',
'data': { 'path': 'str' },
'returns': 'VirtioStatus',
@@ -448,13 +441,13 @@
# device
#
# @statuses: List of decoded configuration statuses of the virtio
-# device
+# device
#
-# @unknown-statuses: Virtio device statuses bitmap that have not been decoded
+# @unknown-statuses: Virtio device statuses bitmap that have not been
+# decoded
#
# Since: 7.2
##
-
{ 'struct': 'VirtioDeviceStatus',
'data': { 'statuses': [ 'str' ],
'*unknown-statuses': 'uint8' } }
@@ -466,14 +459,13 @@
# Vhost User device
#
# @protocols: List of decoded vhost user protocol features of a vhost
-# user device
+# user device
#
# @unknown-protocols: Vhost user device protocol features bitmap that
-# have not been decoded
+# have not been decoded
#
# Since: 7.2
##
-
{ 'struct': 'VhostDeviceProtocols',
'data': { 'protocols': [ 'str' ],
'*unknown-protocols': 'uint64' } }
@@ -481,20 +473,19 @@
##
# @VirtioDeviceFeatures:
#
-# The common fields that apply to most Virtio devices. Some devices
+# The common fields that apply to most Virtio devices. Some devices
# may not have their own device-specific features (e.g. virtio-rng).
#
# @transports: List of transport features of the virtio device
#
# @dev-features: List of device-specific features (if the device has
-# unique features)
+# unique features)
#
# @unknown-dev-features: Virtio device features bitmap that have not
-# been decoded
+# been decoded
#
# Since: 7.2
##
-
{ 'struct': 'VirtioDeviceFeatures',
'data': { 'transports': [ 'str' ],
'*dev-features': [ 'str' ],
@@ -525,7 +516,7 @@
# @vring-used: VirtQueue vring.used (device area)
#
# @last-avail-idx: VirtQueue last_avail_idx or return of vhost_dev
-# vhost_get_vring_base (if vhost active)
+# vhost_get_vring_base (if vhost active)
#
# @shadow-avail-idx: VirtQueue shadow_avail_idx
#
@@ -536,9 +527,7 @@
# @signalled-used-valid: VirtQueue signalled_used_valid flag
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtQueueStatus',
'data': { 'name': 'str',
'queue-index': 'uint16',
@@ -565,16 +554,17 @@
# @queue: VirtQueue index to examine
#
# Features:
+#
# @unstable: This command is meant for debugging.
#
# Returns: VirtQueueStatus of the VirtQueue
#
-# Notes: last_avail_idx will not be displayed in the case where
-# the selected VirtIODevice has a running vhost device and
-# the VirtIODevice VirtQueue index (queue) does not exist for
-# the corresponding vhost device vhost_virtqueue. Also,
-# shadow_avail_idx will not be displayed in the case where
-# the selected VirtIODevice has a running vhost device.
+# Notes: last_avail_idx will not be displayed in the case where the
+# selected VirtIODevice has a running vhost device and the
+# VirtIODevice VirtQueue index (queue) does not exist for the
+# corresponding vhost device vhost_virtqueue. Also,
+# shadow_avail_idx will not be displayed in the case where the
+# selected VirtIODevice has a running vhost device.
#
# Since: 7.2
#
@@ -626,9 +616,7 @@
# "vring-num": 128
# }
# }
-#
##
-
{ 'command': 'x-query-virtio-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
'returns': 'VirtQueueStatus',
@@ -667,9 +655,7 @@
# @used-size: vhost_virtqueue used_size
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtVhostQueueStatus',
'data': { 'name': 'str',
'kick': 'int',
@@ -695,6 +681,7 @@
# @queue: vhost_virtqueue index to examine
#
# Features:
+#
# @unstable: This command is meant for debugging.
#
# Returns: VirtVhostQueueStatus of the vhost_virtqueue
@@ -748,9 +735,7 @@
# "kick": 0
# }
# }
-#
##
-
{ 'command': 'x-query-virtio-vhost-queue-status',
'data': { 'path': 'str', 'queue': 'uint16' },
'returns': 'VirtVhostQueueStatus',
@@ -768,9 +753,7 @@
# @flags: List of descriptor flags
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtioRingDesc',
'data': { 'addr': 'uint64',
'len': 'uint32',
@@ -788,9 +771,7 @@
# @ring: VRingAvail ring[] entry at provided index
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtioRingAvail',
'data': { 'flags': 'uint16',
'idx': 'uint16',
@@ -806,9 +787,7 @@
# @idx: VRingUsed index
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtioRingUsed',
'data': { 'flags': 'uint16',
'idx': 'uint16' } }
@@ -830,9 +809,7 @@
# @used: VRingUsed info
#
# Since: 7.2
-#
##
-
{ 'struct': 'VirtioQueueElement',
'data': { 'name': 'str',
'index': 'uint32',
@@ -849,10 +826,11 @@
#
# @queue: VirtQueue index to examine
#
-# @index: Index of the element in the queue
-# (default: head of the queue)
+# @index: Index of the element in the queue (default: head of the
+# queue)
#
# Features:
+#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioQueueElement information
@@ -945,9 +923,7 @@
# }
# }
# }
-#
##
-
{ 'command': 'x-query-virtio-queue-element',
'data': { 'path': 'str', 'queue': 'uint16', '*index': 'uint16' },
'returns': 'VirtioQueueElement',
