QEMU-Devel Archive on lore.kernel.org
 help / color / Atom feed
From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Cc: "Daniel P. Berrangé" <berrange@redhat.com>,
	"Markus Armbruster" <armbru@redhat.com>,
	"Michael Roth" <mdroth@linux.vnet.ibm.com>,
	"Stefan Hajnoczi" <stefanha@redhat.com>,
	"John Snow" <jsnow@redhat.com>
Subject: [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments
Date: Thu, 13 Feb 2020 17:56:22 +0000
Message-ID: <20200213175647.17628-6-peter.maydell@linaro.org> (raw)
In-Reply-To: <20200213175647.17628-1-peter.maydell@linaro.org>

The texinfo doc generation doesn't care much about indentation
levels, but we would like to add a rST backend, and rST does care
about indentation.

Make the doc comments more strongly consistent about indentation
for multiline constructs like:

@arg: description line 1
      description line 2

Returns: line one
         line 2

so that there is always exactly one space after the colon, and
subsequent lines align with the first.

This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace).  This does mean that we end up with some
over-length lines.

Note that when the documentation for an argument fits on a single
line like this:

@arg: one line only

then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
---
 qga/qapi-schema.json | 62 ++++++++++++++++++++++----------------------
 1 file changed, 31 insertions(+), 31 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 23ce6af597d..7661b2b3b45 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -416,7 +416,7 @@
 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
 #
 # Note: This may fail to properly report the current state as a result of
-# some other guest processes having issued an fs freeze/thaw.
+#       some other guest processes having issued an fs freeze/thaw.
 #
 # Since: 0.15.0
 ##
@@ -431,13 +431,13 @@
 # unfreeze.
 #
 # Note: On Windows, the command is implemented with the help of a
-# Volume Shadow-copy Service DLL helper. The frozen state is limited
-# for up to 10 seconds by VSS.
+#       Volume Shadow-copy Service DLL helper. The frozen state is limited
+#       for up to 10 seconds by VSS.
 #
 # Returns: Number of file systems currently frozen. On error, all filesystems
-# will be thawed. If no filesystems are frozen as a result of this call,
-# then @guest-fsfreeze-status will remain "thawed" and calling
-# @guest-fsfreeze-thaw is not necessary.
+#          will be thawed. If no filesystems are frozen as a result of this call,
+#          then @guest-fsfreeze-status will remain "thawed" and calling
+#          @guest-fsfreeze-thaw is not necessary.
 #
 # Since: 0.15.0
 ##
@@ -455,7 +455,7 @@
 #               Invalid mount points are ignored.
 #
 # Returns: Number of file systems currently frozen. On error, all filesystems
-# will be thawed.
+#          will be thawed.
 #
 # Since: 2.2
 ##
@@ -511,12 +511,12 @@
 # Discard (or "trim") blocks which are not in use by the filesystem.
 #
 # @minimum:
-#       Minimum contiguous free range to discard, in bytes. Free ranges
-#       smaller than this may be ignored (this is a hint and the guest
-#       may not respect it).  By increasing this value, the fstrim
-#       operation will complete more quickly for filesystems with badly
-#       fragmented free space, although not all blocks will be discarded.
-#       The default value is zero, meaning "discard every free block".
+#           Minimum contiguous free range to discard, in bytes. Free ranges
+#           smaller than this may be ignored (this is a hint and the guest
+#           may not respect it).  By increasing this value, the fstrim
+#           operation will complete more quickly for filesystems with badly
+#           fragmented free space, although not all blocks will be discarded.
+#           The default value is zero, meaning "discard every free block".
 #
 # Returns: A @GuestFilesystemTrimResponse which contains the
 #          status of all trimmed paths. (since 2.4)
@@ -693,7 +693,7 @@
 # @ip-addresses: List of addresses assigned to @name
 #
 # @statistics: various statistic counters related to @name
-# (since 2.11)
+#              (since 2.11)
 #
 # Since: 1.1
 ##
@@ -743,7 +743,7 @@
 # This is a read-only operation.
 #
 # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
-# list exactly once, but their order is unspecified.
+#          list exactly once, but their order is unspecified.
 #
 # Since: 1.5
 ##
@@ -937,8 +937,8 @@
 # This is a read-only operation.
 #
 # Returns: The list of all memory blocks the guest knows about.
-# Each memory block is put on the list exactly once, but their order
-# is unspecified.
+#          Each memory block is put on the list exactly once, but their order
+#          is unspecified.
 #
 # Since: 2.3
 ##
@@ -971,9 +971,9 @@
 # @response: the result of memory block operation.
 #
 # @error-code: the error number.
-#               When memory block operation fails, we assign the value of
-#               'errno' to this member, it indicates what goes wrong.
-#               When the operation succeeds, it will be omitted.
+#              When memory block operation fails, we assign the value of
+#              'errno' to this member, it indicates what goes wrong.
+#              When the operation succeeds, it will be omitted.
 #
 # Since: 2.3
 ##
@@ -1040,15 +1040,15 @@
 # @exited: true if process has already terminated.
 # @exitcode: process exit code if it was normally terminated.
 # @signal: signal number (linux) or unhandled exception code
-#       (windows) if the process was abnormally terminated.
+#          (windows) if the process was abnormally terminated.
 # @out-data: base64-encoded stdout of the process
 # @err-data: base64-encoded stderr of the process
-#       Note: @out-data and @err-data are present only
-#       if 'capture-output' was specified for 'guest-exec'
+#            Note: @out-data and @err-data are present only
+#            if 'capture-output' was specified for 'guest-exec'
 # @out-truncated: true if stdout was not fully captured
-#       due to size limitation.
+#                 due to size limitation.
 # @err-truncated: true if stderr was not fully captured
-#       due to size limitation.
+#                 due to size limitation.
 #
 # Since: 2.5
 ##
@@ -1131,8 +1131,8 @@
 
 ##
 # @GuestUser:
-# @user:       Username
-# @domain:     Logon domain (windows only)
+# @user: Username
+# @domain: Logon domain (windows only)
 # @login-time: Time of login of this user on the computer. If multiple
 #              instances of the user are logged in, the earliest login time is
 #              reported. The value is in fractional seconds since epoch time.
@@ -1156,10 +1156,10 @@
 ##
 # @GuestTimezone:
 #
-# @zone:    Timezone name. These values may differ depending on guest/OS and
-#           should only be used for informational purposes.
-# @offset:  Offset to UTC in seconds, negative numbers for time zones west of
-#           GMT, positive numbers for east
+# @zone: Timezone name. These values may differ depending on guest/OS and
+#        should only be used for informational purposes.
+# @offset: Offset to UTC in seconds, negative numbers for time zones west of
+#          GMT, positive numbers for east
 #
 # Since: 2.10
 ##
-- 
2.20.1



  parent reply index

Thread overview: 69+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-13 17:56 [PATCH v2 00/30] Convert QAPI doc comments to generate rST instead of texinfo Peter Maydell
2020-02-13 17:56 ` [PATCH v2 01/30] configure: Allow user to specify sphinx-build binary Peter Maydell
2020-02-14  6:33   ` Markus Armbruster
2020-02-14  9:21     ` Peter Maydell
2020-02-14 12:20       ` Markus Armbruster
2020-02-14 12:39         ` Peter Maydell
2020-02-14 17:18           ` Markus Armbruster
2020-02-14 17:36             ` Peter Maydell
2020-02-15 10:37               ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 02/30] configure: Check that sphinx-build is using Python 3 Peter Maydell
2020-02-13 17:56 ` [PATCH v2 03/30] Makefile: Fix typo in dependency list for interop manpages Peter Maydell
2020-02-13 17:56 ` [PATCH v2 04/30] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment Peter Maydell
2020-02-13 17:56 ` Peter Maydell [this message]
2020-02-14 12:36   ` [PATCH v2 05/30] qga/qapi-schema.json: Fix indent level on doc comments Markus Armbruster
2020-02-14 12:40     ` Peter Maydell
2020-02-14 14:26       ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 06/30] qga/qapi-schema.json: minor format fixups for rST Peter Maydell
2020-02-14 12:46   ` Markus Armbruster
2020-02-14 14:33     ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 07/30] qapi/block-core.json: Use literal block for ascii art Peter Maydell
2020-02-13 22:59   ` Aleksandar Markovic
2020-02-15 20:56     ` Philippe Mathieu-Daudé
2020-02-15 21:01       ` Aleksandar Markovic
2020-02-17  0:44         ` Philippe Mathieu-Daudé
2020-02-17  5:53           ` Samuel Thibault
2020-02-14 12:53   ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 08/30] qapi: Use ':' after @argument in doc comments Peter Maydell
2020-02-14 13:02   ` Markus Armbruster
2020-02-14 13:28     ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 09/30] qapi: Fix indent level on doc comments in json files Peter Maydell
2020-02-14 13:45   ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 10/30] qapi: Remove hardcoded tabs Peter Maydell
2020-02-13 17:56 ` [PATCH v2 11/30] qapi/ui.json: Put input-send-event body text in the right place Peter Maydell
2020-02-13 17:56 ` [PATCH v2 12/30] qapi/ui.json: Avoid `...' texinfo style quoting Peter Maydell
2020-02-13 17:56 ` [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists Peter Maydell
2020-02-13 17:56 ` [PATCH v2 14/30] qapi/ui.json: " Peter Maydell
2020-02-14 14:20   ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: " Peter Maydell
2020-02-14 14:23   ` Markus Armbruster
2020-02-14 14:28     ` Peter Maydell
2020-02-14 15:46       ` Markus Armbruster
2020-02-14 15:48         ` Peter Maydell
2020-02-13 17:56 ` [PATCH v2 16/30] qapi: Add blank lines before " Peter Maydell
2020-02-14 14:33   ` Markus Armbruster
2020-02-14 16:02     ` Markus Armbruster
2020-02-14 16:16       ` Peter Maydell
2020-02-14 17:11         ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 17/30] qapi/migration.json: Replace _this_ with *this* Peter Maydell
2020-02-13 19:02   ` Philippe Mathieu-Daudé
2020-02-14 14:35   ` Markus Armbruster
2020-02-13 17:56 ` [PATCH v2 18/30] qapi: Delete all the "foo: dropped in n.n" notes Peter Maydell
2020-02-14  6:55   ` Markus Armbruster
2020-02-14 15:13     ` Markus Armbruster
2020-02-14 15:20       ` Peter Maydell
2020-02-13 17:56 ` [PATCH v2 19/30] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Peter Maydell
2020-02-13 17:56 ` [PATCH v2 20/30] qapi/machine.json: Escape a literal '*' in doc comment Peter Maydell
2020-02-13 19:01   ` Philippe Mathieu-Daudé
2020-02-13 17:56 ` [PATCH v2 21/30] tests/qapi/doc-good.json: Clean up markup Peter Maydell
2020-02-13 17:56 ` [PATCH v2 22/30] scripts/qapi: Move doc-comment whitespace stripping to doc.py Peter Maydell
2020-02-13 17:56 ` [PATCH v2 23/30] scripts/qapi/parser.py: improve doc comment indent handling Peter Maydell
2020-02-13 17:56 ` [PATCH v2 24/30] docs/sphinx: Add new qapi-doc Sphinx extension Peter Maydell
2020-02-13 17:56 ` [PATCH v2 25/30] docs/interop: Convert qemu-ga-ref to rST Peter Maydell
2020-02-13 17:56 ` [PATCH v2 26/30] docs/interop: Convert qemu-qmp-ref " Peter Maydell
2020-02-17 15:10   ` Peter Maydell
2020-02-13 17:56 ` [PATCH v2 27/30] qapi: Use rST markup for literal blocks Peter Maydell
2020-02-13 17:56 ` [PATCH v2 28/30] qga/qapi-schema.json: Add some headings Peter Maydell
2020-02-13 17:56 ` [PATCH v2 29/30] scripts/qapi: Remove texinfo generation support Peter Maydell
2020-02-13 17:56 ` [PATCH v2 30/30] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Peter Maydell
2020-02-13 20:51 ` [PATCH v2 00/30] Convert QAPI doc comments to generate rST instead of texinfo no-reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200213175647.17628-6-peter.maydell@linaro.org \
    --to=peter.maydell@linaro.org \
    --cc=armbru@redhat.com \
    --cc=berrange@redhat.com \
    --cc=jsnow@redhat.com \
    --cc=mdroth@linux.vnet.ibm.com \
    --cc=qemu-devel@nongnu.org \
    --cc=stefanha@redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

QEMU-Devel Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/qemu-devel/0 qemu-devel/git/0.git
	git clone --mirror https://lore.kernel.org/qemu-devel/1 qemu-devel/git/1.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 qemu-devel qemu-devel/ https://lore.kernel.org/qemu-devel \
		qemu-devel@nongnu.org
	public-inbox-index qemu-devel

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.nongnu.qemu-devel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git