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]

1 files changed, 74 insertions, 65 deletions

diff --git a/qapi/job.json b/qapi/job.json
index 9e29a796c5..7f0ba090de 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -20,13 +20,17 @@
 #
 # @create: image creation job type, see "blockdev-create" (since 3.0)
 #
-# @amend: image options amend job type, see "x-blockdev-amend" (since 5.1)
+# @amend: image options amend job type, see "x-blockdev-amend" (since
+#     5.1)
 #
-# @snapshot-load: snapshot load job type, see "snapshot-load" (since 6.0)
+# @snapshot-load: snapshot load job type, see "snapshot-load" (since
+#     6.0)
 #
-# @snapshot-save: snapshot save job type, see "snapshot-save" (since 6.0)
+# @snapshot-save: snapshot save job type, see "snapshot-save" (since
+#     6.0)
 #
-# @snapshot-delete: snapshot delete job type, see "snapshot-delete" (since 6.0)
+# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
+#     (since 6.0)
 #
 # Since: 1.7
 ##
@@ -39,41 +43,42 @@
 #
 # Indicates the present state of a given job in its lifetime.
 #
-# @undefined: Erroneous, default state. Should not ever be visible.
+# @undefined: Erroneous, default state.  Should not ever be visible.
 #
 # @created: The job has been created, but not yet started.
 #
 # @running: The job is currently running.
 #
-# @paused: The job is running, but paused. The pause may be requested by
-#          either the QMP user or by internal processes.
+# @paused: The job is running, but paused.  The pause may be requested
+#     by either the QMP user or by internal processes.
 #
-# @ready: The job is running, but is ready for the user to signal completion.
-#         This is used for long-running jobs like mirror that are designed to
-#         run indefinitely.
+# @ready: The job is running, but is ready for the user to signal
+#     completion.  This is used for long-running jobs like mirror that
+#     are designed to run indefinitely.
 #
-# @standby: The job is ready, but paused. This is nearly identical to @paused.
-#           The job may return to @ready or otherwise be canceled.
+# @standby: The job is ready, but paused.  This is nearly identical to
+#     @paused.  The job may return to @ready or otherwise be canceled.
 #
-# @waiting: The job is waiting for other jobs in the transaction to converge
-#           to the waiting state. This status will likely not be visible for
-#           the last job in a transaction.
+# @waiting: The job is waiting for other jobs in the transaction to
+#     converge to the waiting state.  This status will likely not be
+#     visible for the last job in a transaction.
 #
-# @pending: The job has finished its work, but has finalization steps that it
-#           needs to make prior to completing. These changes will require
-#           manual intervention via @job-finalize if auto-finalize was set to
-#           false. These pending changes may still fail.
+# @pending: The job has finished its work, but has finalization steps
+#     that it needs to make prior to completing.  These changes will
+#     require manual intervention via @job-finalize if auto-finalize
+#     was set to false.  These pending changes may still fail.
 #
-# @aborting: The job is in the process of being aborted, and will finish with
-#            an error. The job will afterwards report that it is @concluded.
-#            This status may not be visible to the management process.
+# @aborting: The job is in the process of being aborted, and will
+#     finish with an error.  The job will afterwards report that it is
+#     @concluded.  This status may not be visible to the management
+#     process.
 #
-# @concluded: The job has finished all work. If auto-dismiss was set to false,
-#             the job will remain in the query list until it is dismissed via
-#             @job-dismiss.
+# @concluded: The job has finished all work.  If auto-dismiss was set
+#     to false, the job will remain in the query list until it is
+#     dismissed via @job-dismiss.
 #
-# @null: The job is in the process of being dismantled. This state should not
-#        ever be visible externally.
+# @null: The job is in the process of being dismantled.  This state
+#     should not ever be visible externally.
 #
 # Since: 2.12
 ##
@@ -112,6 +117,7 @@
 # Emitted when a job transitions to a different status.
 #
 # @id: The job identifier
+#
 # @status: The new job status
 #
 # Since: 3.0
@@ -125,12 +131,12 @@
 #
 # Pause an active job.
 #
-# This command returns immediately after marking the active job for pausing.
-# Pausing an already paused job is an error.
+# This command returns immediately after marking the active job for
+# pausing.  Pausing an already paused job is an error.
 #
-# The job will pause as soon as possible, which means transitioning into the
-# PAUSED state if it was RUNNING, or into STANDBY if it was READY. The
-# corresponding JOB_STATUS_CHANGE event will be emitted.
+# The job will pause as soon as possible, which means transitioning
+# into the PAUSED state if it was RUNNING, or into STANDBY if it was
+# READY. The corresponding JOB_STATUS_CHANGE event will be emitted.
 #
 # Cancelling a paused job automatically resumes it.
 #
@@ -145,8 +151,8 @@
 #
 # Resume a paused job.
 #
-# This command returns immediately after resuming a paused job. Resuming an
-# already running job is an error.
+# This command returns immediately after resuming a paused job.
+# Resuming an already running job is an error.
 #
 # @id: The job identifier.
 #
@@ -161,11 +167,11 @@
 # This command returns immediately after marking the active job for
 # cancellation.
 #
-# The job will cancel as soon as possible and then emit a JOB_STATUS_CHANGE
-# event. Usually, the status will change to ABORTING, but it is possible that
-# a job successfully completes (e.g. because it was almost done and there was
-# no opportunity to cancel earlier than completing the job) and transitions to
-# PENDING instead.
+# The job will cancel as soon as possible and then emit a
+# JOB_STATUS_CHANGE event.  Usually, the status will change to
+# ABORTING, but it is possible that a job successfully completes (e.g.
+# because it was almost done and there was no opportunity to cancel
+# earlier than completing the job) and transitions to PENDING instead.
 #
 # @id: The job identifier.
 #
@@ -187,12 +193,14 @@
 ##
 # @job-dismiss:
 #
-# Deletes a job that is in the CONCLUDED state. This command only needs to be
-# run explicitly for jobs that don't have automatic dismiss enabled.
+# Deletes a job that is in the CONCLUDED state.  This command only
+# needs to be run explicitly for jobs that don't have automatic
+# dismiss enabled.
 #
-# This command will refuse to operate on any job that has not yet reached its
-# terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of JOB_READY
-# event, job-cancel or job-complete will still need to be used as appropriate.
+# This command will refuse to operate on any job that has not yet
+# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that make
+# use of JOB_READY event, job-cancel or job-complete will still need
+# to be used as appropriate.
 #
 # @id: The job identifier.
 #
@@ -203,16 +211,17 @@
 ##
 # @job-finalize:
 #
-# Instructs all jobs in a transaction (or a single job if it is not part of any
-# transaction) to finalize any graph changes and do any necessary cleanup. This
-# command requires that all involved jobs are in the PENDING state.
+# Instructs all jobs in a transaction (or a single job if it is not
+# part of any transaction) to finalize any graph changes and do any
+# necessary cleanup.  This command requires that all involved jobs are
+# in the PENDING state.
 #
-# For jobs in a transaction, instructing one job to finalize will force
-# ALL jobs in the transaction to finalize, so it is only necessary to instruct
-# a single member job to finalize.
+# For jobs in a transaction, instructing one job to finalize will
+# force ALL jobs in the transaction to finalize, so it is only
+# necessary to instruct a single member job to finalize.
 #
-# @id: The identifier of any job in the transaction, or of a job that is not
-#      part of any transaction.
+# @id: The identifier of any job in the transaction, or of a job that
+#     is not part of any transaction.
 #
 # Since: 3.0
 ##
@@ -229,22 +238,22 @@
 #
 # @status: Current job state/status
 #
-# @current-progress: Progress made until now. The unit is arbitrary and the
-#                    value can only meaningfully be used for the ratio of
-#                    @current-progress to @total-progress. The value is
-#                    monotonically increasing.
+# @current-progress: Progress made until now.  The unit is arbitrary
+#     and the value can only meaningfully be used for the ratio of
+#     @current-progress to @total-progress.  The value is
+#     monotonically increasing.
 #
-# @total-progress: Estimated @current-progress value at the completion of
-#                  the job. This value can arbitrarily change while the
-#                  job is running, in both directions.
+# @total-progress: Estimated @current-progress value at the completion
+#     of the job.  This value can arbitrarily change while the job is
+#     running, in both directions.
 #
-# @error: If this field is present, the job failed; if it is
-#         still missing in the CONCLUDED state, this indicates
-#         successful completion.
+# @error: If this field is present, the job failed; if it is still
+#     missing in the CONCLUDED state, this indicates successful
+#     completion.
 #
-#         The value is a human-readable error message to describe
-#         the reason for the job failure. It should not be parsed
-#         by applications.
+#     The value is a human-readable error message to describe the
+#     reason for the job failure.  It should not be parsed by
+#     applications.
 #
 # Since: 3.0
 ##