From 1ed1d4d60885059cee10a411653c5868a0c13097 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 5 Feb 2024 08:46:58 +0100 Subject: [PATCH] qapi: Indent tagged doc comment sections properly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/devel/qapi-code-gen demands that the "second and subsequent lines of sections other than "Example"/"Examples" should be indented". Commit a937b6aa739q (qapi: Reformat doc comments to conform to current conventions) missed a few instances, and messed up a few others. Clean that up. Signed-off-by: Markus Armbruster Message-ID: <20240205074709.3613229-5-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- qapi/migration.json | 46 ++++++++++++++++----------------- qapi/misc.json | 12 +++++---- qapi/qdev.json | 12 ++++----- tests/qapi-schema/doc-good.json | 10 +++---- tests/qapi-schema/doc-good.out | 2 +- 5 files changed, 42 insertions(+), 40 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 819708321d..bf89765a26 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1699,24 +1699,24 @@ # # Notes: # -# 1. The 'query-migrate' command should be used to check migration's -# progress and final result (this information is provided by the -# 'status' member) +# 1. The 'query-migrate' command should be used to check +# migration's progress and final result (this information is +# provided by the 'status' member) # -# 2. All boolean arguments default to false +# 2. All boolean arguments default to false # -# 3. The user Monitor's "detach" argument is invalid in QMP and should -# not be used +# 3. The user Monitor's "detach" argument is invalid in QMP and +# should not be used # -# 4. The uri argument should have the Uniform Resource Identifier of -# default destination VM. This connection will be bound to default -# network. +# 4. The uri argument should have the Uniform Resource Identifier +# of default destination VM. This connection will be bound to +# default network. # -# 5. For now, number of migration streams is restricted to one, i.e -# number of items in 'channels' list is just 1. +# 5. For now, number of migration streams is restricted to one, +# i.e number of items in 'channels' list is just 1. # -# 6. The 'uri' and 'channels' arguments are mutually exclusive; -# exactly one of the two should be present. +# 6. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # # Example: # @@ -1781,20 +1781,20 @@ # # Notes: # -# 1. It's a bad idea to use a string for the uri, but it needs -# to stay compatible with -incoming and the format of the uri -# is already exposed above libvirt. +# 1. It's a bad idea to use a string for the uri, but it needs to +# stay compatible with -incoming and the format of the uri is +# already exposed above libvirt. # -# 2. QEMU must be started with -incoming defer to allow -# migrate-incoming to be used. +# 2. QEMU must be started with -incoming defer to allow +# migrate-incoming to be used. # -# 3. The uri format is the same as for -incoming +# 3. The uri format is the same as for -incoming # -# 5. For now, number of migration streams is restricted to one, i.e -# number of items in 'channels' list is just 1. +# 5. For now, number of migration streams is restricted to one, +# i.e number of items in 'channels' list is just 1. # -# 4. The 'uri' and 'channels' arguments are mutually exclusive; -# exactly one of the two should be present. +# 4. The 'uri' and 'channels' arguments are mutually exclusive; +# exactly one of the two should be present. # # Example: # diff --git a/qapi/misc.json b/qapi/misc.json index 2ca8c39874..4108a0c951 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -348,9 +348,10 @@ # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fdset-id is not specified, a new fd set will be created. +# If @fdset-id is not specified, a new fd set will be created. # # Since: 1.2 # @@ -379,10 +380,11 @@ # # Since: 1.2 # -# Notes: The list of fd sets is shared by all monitor connections. +# Notes: +# The list of fd sets is shared by all monitor connections. # -# If @fd is not specified, all file descriptors in @fdset-id will be -# removed. +# If @fd is not specified, all file descriptors in @fdset-id will +# be removed. # # Example: # diff --git a/qapi/qdev.json b/qapi/qdev.json index 25bac5e611..3b3ccfa413 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -53,14 +53,14 @@ # # Notes: # -# 1. Additional arguments depend on the type. +# 1. Additional arguments depend on the type. # -# 2. For detailed information about this command, please refer to the -# 'docs/qdev-device-use.txt' file. +# 2. For detailed information about this command, please refer to +# the 'docs/qdev-device-use.txt' file. # -# 3. It's possible to list device properties by running QEMU with the -# "-device DEVICE,help" command-line argument, where DEVICE is the -# device's name +# 3. It's possible to list device properties by running QEMU with +# the "-device DEVICE,help" command-line argument, where DEVICE +# is the device's name # # Example: # diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 354dfdf461..976f9e1aaa 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -73,8 +73,8 @@ # @Base: # # @base1: -# description starts on a new line, -# not indented +# description starts on a new line, +# minimally indented ## { 'struct': 'Base', 'data': { 'base1': 'Enum' }, 'if': { 'all': ['IFALL1', 'IFALL2'] } } @@ -155,10 +155,10 @@ # TODO: frobnicate # Notes: # -# - Lorem ipsum dolor sit amet -# - Ut enim ad minim veniam +# - Lorem ipsum dolor sit amet +# - Ut enim ad minim veniam # -# Duis aute irure dolor +# Duis aute irure dolor # Example: # # -> in diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 24d9ea954d..34ee74af4b 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -118,7 +118,7 @@ doc symbol=Base arg=base1 description starts on a new line, -not indented +minimally indented doc symbol=Variant1 body= A paragraph