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]

qapi/acpi.json

@@ -14,18 +14,19 @@
 #
 # Specify an ACPI table on the command line to load.
 #
-# At most one of @file and @data can be specified. The list of files specified
-# by any one of them is loaded and concatenated in order. If both are omitted,
-# @data is implied.
+# At most one of @file and @data can be specified.  The list of files
+# specified by any one of them is loaded and concatenated in order.
+# If both are omitted, @data is implied.
 #
-# Other fields / optargs can be used to override fields of the generic ACPI
-# table header; refer to the ACPI specification 5.0, section 5.2.6 System
-# Description Table Header. If a header field is not overridden, then the
-# corresponding value from the concatenated blob is used (in case of @file), or
-# it is filled in with a hard-coded value (in case of @data).
+# Other fields / optargs can be used to override fields of the generic
+# ACPI table header; refer to the ACPI specification 5.0, section
+# 5.2.6 System Description Table Header.  If a header field is not
+# overridden, then the corresponding value from the concatenated blob
+# is used (in case of @file), or it is filled in with a hard-coded
+# value (in case of @data).
 #
-# String fields are copied into the matching ACPI member from lowest address
-# upwards, and silently truncated / NUL-padded to length.
+# String fields are copied into the matching ACPI member from lowest
+# address upwards, and silently truncated / NUL-padded to length.
 #
 # @sig: table signature / identifier (4 bytes)
 #
@@ -38,20 +39,20 @@
 # @oem_rev: OEM-supplied revision number (4 bytes)
 #
 # @asl_compiler_id: identifier of the utility that created the table
-#                   (4 bytes)
+#     (4 bytes)
 #
 # @asl_compiler_rev: revision number of the utility that created the
-#                    table (4 bytes)
+#     table (4 bytes)
 #
-# @file: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob is expected to
-#        have an ACPI table header. At least one file is required. This field
-#        excludes @data.
+# @file: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob is expected to have an
+#     ACPI table header.  At least one file is required.  This field
+#     excludes @data.
 #
-# @data: colon (:) separated list of pathnames to load and
-#        concatenate as table data. The resultant binary blob must not have an
-#        ACPI table header. At least one file is required. This field excludes
-#        @file.
+# @data: colon (:) separated list of pathnames to load and concatenate
+#     as table data.  The resultant binary blob must not have an ACPI
+#     table header.  At least one file is required.  This field
+#     excludes @file.
 #
 # Since: 1.5
 ##
@@ -71,16 +72,17 @@
 # @ACPISlotType:
 #
 # @DIMM: memory slot
+#
 # @CPU: logical CPU slot (since 2.7)
 ##
 { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
 
 ##
 # @ACPIOSTInfo:
 #
-# OSPM Status Indication for a device
-# For description of possible values of @source and @status fields
-# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
+# OSPM Status Indication for a device For description of possible
+# values of @source and @status fields see "_OST (OSPM Status
+# Indication)" chapter of ACPI5.0 spec.
 #
 # @device: device ID associated with slot
 #
@@ -117,7 +119,6 @@
 #                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
 #                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
 #    ]}
-#
 ##
 { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
 
@@ -136,7 +137,6 @@
 #      "data": { "info": { "device": "d1", "slot": "0",
 #                          "slot-type": "DIMM", "source": 1, "status": 0 } },
 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
-#
 ##
 { 'event': 'ACPI_DEVICE_OST',
      'data': { 'info': 'ACPIOSTInfo' } }

qapi/audio.json

@@ -16,24 +16,24 @@
 # General audio backend options that are used for both playback and
 # recording.
 #
-# @mixing-engine: use QEMU's mixing engine to mix all streams inside QEMU and
-#                 convert audio formats when not supported by the backend. When
-#                 set to off, fixed-settings must be also off (default on,
-#                 since 4.2)
+# @mixing-engine: use QEMU's mixing engine to mix all streams inside
+#     QEMU and convert audio formats when not supported by the
+#     backend.  When set to off, fixed-settings must be also off
+#     (default on, since 4.2)
 #
-# @fixed-settings: use fixed settings for host input/output. When off,
-#                  frequency, channels and format must not be
-#                  specified (default true)
+# @fixed-settings: use fixed settings for host input/output.  When
+#     off, frequency, channels and format must not be specified
+#     (default true)
 #
-# @frequency: frequency to use when using fixed settings
-#             (default 44100)
+# @frequency: frequency to use when using fixed settings (default
+#     44100)
 #
 # @channels: number of channels when using fixed settings (default 2)
 #
 # @voices: number of voices to use (default 1)
 #
-# @format: sample format to use when using fixed settings
-#          (default s16)
+# @format: sample format to use when using fixed settings (default
+#     s16)
 #
 # @buffer-length: the buffer length in microseconds
 #
@@ -76,7 +76,7 @@
 # @period-length: the period length in microseconds
 #
 # @try-poll: attempt to use poll mode, falling back to non-polling
-#            access on failure (default true)
+#     access on failure (default true)
 #
 # Since: 4.0
 ##
@@ -131,8 +131,8 @@
 ##
 # @AudiodevCoreaudioPerDirectionOptions:
 #
-# Options of the Core Audio backend that are used for both playback and
-# recording.
+# Options of the Core Audio backend that are used for both playback
+# and recording.
 #
 # @buffer-count: number of buffers
 #
@@ -168,8 +168,8 @@
 #
 # @out: options of the playback stream
 #
-# @latency: add extra latency to playback in microseconds
-#           (default 10000)
+# @latency: add extra latency to playback in microseconds (default
+#     10000)
 #
 # Since: 4.0
 ##
@@ -185,21 +185,22 @@
 # Options of the JACK backend that are used for both playback and
 # recording.
 #
-# @server-name: select from among several possible concurrent server instances
-#               (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
+# @server-name: select from among several possible concurrent server
+#     instances (default: environment variable $JACK_DEFAULT_SERVER if
+#     set, else "default")
 #
-# @client-name: the client name to use. The server will modify this name to
-#               create a unique variant, if needed unless @exact-name is true (default: the
-#               guest's name)
+# @client-name: the client name to use.  The server will modify this
+#     name to create a unique variant, if needed unless @exact-name is
+#     true (default: the guest's name)
 #
-# @connect-ports: if set, a regular expression of JACK client port name(s) to
-#                 monitor for and automatically connect to
+# @connect-ports: if set, a regular expression of JACK client port
+#     name(s) to monitor for and automatically connect to
 #
-# @start-server: start a jack server process if one is not already present
-#                (default: false)
+# @start-server: start a jack server process if one is not already
+#     present (default: false)
 #
-# @exact-name: use the exact name requested otherwise JACK automatically
-#              generates a unique one, if needed (default: false)
+# @exact-name: use the exact name requested otherwise JACK
+#     automatically generates a unique one, if needed (default: false)
 #
 # Since: 5.1
 ##
@@ -239,7 +240,7 @@
 # @buffer-count: number of buffers
 #
 # @try-poll: attempt to use poll mode, falling back to non-polling
-#            access on failure (default true)
+#     access on failure (default true)
 #
 # Since: 4.0
 ##
@@ -260,15 +261,15 @@
 # @out: options of the playback stream
 #
 # @try-mmap: try using memory-mapped access, falling back to
-#            non-memory-mapped access on failure (default true)
+#     non-memory-mapped access on failure (default true)
 #
-# @exclusive: open device in exclusive mode (vmix won't work)
-#             (default false)
+# @exclusive: open device in exclusive mode (vmix won't work) (default
+#     false)
 #
 # @dsp-policy: set the timing policy of the device (between 0 and 10,
-#              where smaller number means smaller latency but higher
-#              CPU usage) or -1 to use fragment mode (option ignored
-#              on some platforms) (default 5)
+#     where smaller number means smaller latency but higher CPU usage)
+#     or -1 to use fragment mode (option ignored on some platforms)
+#     (default 5)
 #
 # Since: 4.0
 ##
@@ -283,18 +284,18 @@
 ##
 # @AudiodevPaPerDirectionOptions:
 #
-# Options of the Pulseaudio backend that are used for both playback and
-# recording.
+# Options of the Pulseaudio backend that are used for both playback
+# and recording.
 #
 # @name: name of the sink/source to use
 #
 # @stream-name: name of the PulseAudio stream created by qemu.  Can be
-#               used to identify the stream in PulseAudio when you
-#               create multiple PulseAudio devices or run multiple qemu
-#               instances (default: audiodev's id, since 4.2)
+#     used to identify the stream in PulseAudio when you create
+#     multiple PulseAudio devices or run multiple qemu instances
+#     (default: audiodev's id, since 4.2)
 #
 # @latency: latency you want PulseAudio to achieve in microseconds
-#           (default 15000)
+#     (default 15000)
 #
 # Since: 4.0
 ##
@@ -333,12 +334,12 @@
 # @name: name of the sink/source to use
 #
 # @stream-name: name of the Pipewire stream created by qemu.  Can be
-#               used to identify the stream in Pipewire when you
-#               create multiple Pipewire devices or run multiple qemu
-#               instances (default: audiodev's id)
+#     used to identify the stream in Pipewire when you create multiple
+#     Pipewire devices or run multiple qemu instances (default:
+#     audiodev's id)
 #
 # @latency: latency you want Pipewire to achieve in microseconds
-#           (default 46000)
+#     (default 46000)
 #
 # Since: 8.1
 ##
@@ -472,7 +473,8 @@
 #
 # @driver: the backend driver to use
 #
-# @timer-period: timer period (in microseconds, 0: use lowest possible)
+# @timer-period: timer period (in microseconds, 0: use lowest
+#     possible)
 #
 # Since: 4.0
 ##
@@ -516,7 +518,6 @@
 # Returns: array of @Audiodev
 #
 # Since: 8.0
-#
 ##
 { 'command': 'query-audiodevs',
   'returns': ['Audiodev'] }

qapi/authz.json

@@ -11,6 +11,7 @@
 # The authorization policy result
 #
 # @deny: deny access
+#
 # @allow: allow access
 #
 # Since: 4.0
@@ -25,6 +26,7 @@
 # The authorization policy match format
 #
 # @exact: an exact string match
+#
 # @glob: string with ? and * shell wildcard support
 #
 # Since: 4.0
@@ -39,7 +41,9 @@
 # A single authorization rule.
 #
 # @match: a string or glob to match against a user identity
+#
 # @policy: the result to return if @match evaluates to true
+#
 # @format: the format of the @match rule (default 'exact')
 #
 # Since: 4.0
@@ -54,7 +58,8 @@
 #
 # Properties for authz-list objects.
 #
-# @policy: Default policy to apply when no rule matches (default: deny)
+# @policy: Default policy to apply when no rule matches (default:
+#     deny)
 #
 # @rules: Authorization rules based on matching user
 #
@@ -69,14 +74,14 @@
 #
 # Properties for authz-listfile objects.
 #
-# @filename: File name to load the configuration from. The file must
-#            contain valid JSON for AuthZListProperties.
+# @filename: File name to load the configuration from.  The file must
+#     contain valid JSON for AuthZListProperties.
 #
-# @refresh: If true, inotify is used to monitor the file, automatically
-#           reloading changes. If an error occurs during reloading, all
-#           authorizations will fail until the file is next successfully
-#           loaded. (default: true if the binary was built with
-#           CONFIG_INOTIFY1, false otherwise)
+# @refresh: If true, inotify is used to monitor the file,
+#     automatically reloading changes.  If an error occurs during
+#     reloading, all authorizations will fail until the file is next
+#     successfully loaded.  (default: true if the binary was built
+#     with CONFIG_INOTIFY1, false otherwise)
 #
 # Since: 4.0
 ##
@@ -101,10 +106,10 @@
 #
 # Properties for authz-simple objects.
 #
-# @identity: Identifies the allowed user. Its format depends on the network
-#            service that authorization object is associated with. For
-#            authorizing based on TLS x509 certificates, the identity must be
-#            the x509 distinguished name.
+# @identity: Identifies the allowed user.  Its format depends on the
+#     network service that authorization object is associated with.
+#     For authorizing based on TLS x509 certificates, the identity
+#     must be the x509 distinguished name.
 #
 # Since: 4.0
 ##