diff mbox series

[v2,15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists

Message ID 20200213175647.17628-16-peter.maydell@linaro.org
State Superseded
Headers show
Series Convert QAPI doc comments to generate rST instead of texinfo | expand

Commit Message

Peter Maydell Feb. 13, 2020, 5:56 p.m. UTC 
A JSON block comment like this:
     Returns: nothing on success
              If @node is not a valid block device, DeviceNotFound
              If @name is not found, GenericError with an explanation

renders like this:

     Returns: nothing on success If node is not a valid block device,
     DeviceNotFound If name is not found, GenericError with an explanation

because whitespace is not significant.

Use an actual bulleted list, so that the formatting is correct.

This commit gathers up the remaining json files which had
places needing this fix.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---
v1->v2: minor commit msg tweak
---
 qapi/block.json | 33 ++++++++++++++-------------------
 qapi/misc.json  | 36 ++++++++++++++++--------------------
 qapi/tpm.json   |  4 ++--
 3 files changed, 32 insertions(+), 41 deletions(-)

-- 
2.20.1

Comments

Markus Armbruster Feb. 14, 2020, 2:23 p.m. UTC | #1 
Peter Maydell <peter.maydell@linaro.org> writes:

> A JSON block comment like this:

>      Returns: nothing on success

>               If @node is not a valid block device, DeviceNotFound

>               If @name is not found, GenericError with an explanation

>

> renders like this:

>

>      Returns: nothing on success If node is not a valid block device,

>      DeviceNotFound If name is not found, GenericError with an explanation

>

> because whitespace is not significant.

>

> Use an actual bulleted list, so that the formatting is correct.

>

> This commit gathers up the remaining json files which had

> places needing this fix.

>

> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Reviewed-by: Markus Armbruster <armbru@redhat.com>


What's the rationale for the split between

    [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists
    [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists
    [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists

?
Peter Maydell Feb. 14, 2020, 2:28 p.m. UTC | #2 
On Fri, 14 Feb 2020 at 14:23, Markus Armbruster <armbru@redhat.com> wrote:
> What's the rationale for the split between

>

>     [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists

>     [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists

>     [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists

>

> ?


Just keeping down the size of individual patches for ease of
review. ui.json and block-core.json both had enough uses that
needed fixing to feel like reasonably patch-sized amounts. This
patch is all the straggler files, none of which had numerous
enough changes to seem worth splitting further.

thanks
-- PMM
Markus Armbruster Feb. 14, 2020, 3:46 p.m. UTC | #3 
Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 14 Feb 2020 at 14:23, Markus Armbruster <armbru@redhat.com> wrote:

>> What's the rationale for the split between

>>

>>     [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists

>>     [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists

>>     [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists

>>

>> ?

>

> Just keeping down the size of individual patches for ease of

> review. ui.json and block-core.json both had enough uses that

> needed fixing to feel like reasonably patch-sized amounts. This

> patch is all the straggler files, none of which had numerous

> enough changes to seem worth splitting further.


I see.

Separating block.json and block-core.json is a bit odd.

Mind if I squash all three?
Peter Maydell Feb. 14, 2020, 3:48 p.m. UTC | #4 
On Fri, 14 Feb 2020 at 15:46, Markus Armbruster <armbru@redhat.com> wrote:
>

> Peter Maydell <peter.maydell@linaro.org> writes:

>

> > On Fri, 14 Feb 2020 at 14:23, Markus Armbruster <armbru@redhat.com> wrote:

> >> What's the rationale for the split between

> >>

> >>     [PATCH v2 13/30] qapi/block-core.json: Use explicit bulleted lists

> >>     [PATCH v2 14/30] qapi/ui.json: Use explicit bulleted lists

> >>     [PATCH v2 15/30] qapi/{block, misc, tmp, net}.json: Use explicit bulleted lists

> >>

> >> ?

> >

> > Just keeping down the size of individual patches for ease of

> > review. ui.json and block-core.json both had enough uses that

> > needed fixing to feel like reasonably patch-sized amounts. This

> > patch is all the straggler files, none of which had numerous

> > enough changes to seem worth splitting further.

>

> I see.

>

> Separating block.json and block-core.json is a bit odd.

>

> Mind if I squash all three?


I don't mind; the split was as I say mostly just to keep
commit sizes down, so if all-squashed-together works better
for you as a reviewer feel free.

thanks
-- PMM
diff mbox series

Patch

diff --git a/qapi/block.json b/qapi/block.json
index 65eaacf31ad..da19834db41 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -115,15 +115,12 @@ 
 #
 # For the arguments, see the documentation of BlockdevSnapshotInternal.
 #
-# Returns: nothing on success
-#
-#          If @device is not a valid block device, GenericError
-#
-#          If any snapshot matching @name exists, or @name is empty,
-#          GenericError
-#
-#          If the format of the image used does not support it,
-#          BlockFormatFeatureNotSupported
+# Returns: - nothing on success
+#          - If @device is not a valid block device, GenericError
+#          - If any snapshot matching @name exists, or @name is empty,
+#            GenericError
+#          - If the format of the image used does not support it,
+#            BlockFormatFeatureNotSupported
 #
 # Since: 1.7
 #
@@ -154,12 +151,12 @@ 
 #
 # @name: optional the snapshot's name to be deleted
 #
-# Returns: SnapshotInfo on success
-#          If @device is not a valid block device, GenericError
-#          If snapshot not found, GenericError
-#          If the format of the image used does not support it,
-#          BlockFormatFeatureNotSupported
-#          If @id and @name are both not specified, GenericError
+# Returns: - SnapshotInfo on success
+#          - If @device is not a valid block device, GenericError
+#          - If snapshot not found, GenericError
+#          - If the format of the image used does not support it,
+#            BlockFormatFeatureNotSupported
+#          - If @id and @name are both not specified, GenericError
 #
 # Since: 1.7
 #
@@ -197,10 +194,8 @@ 
 # @force: If true, eject regardless of whether the drive is locked.
 #         If not specified, the default value is false.
 #
-# Returns:  Nothing on success
-#
-#           If @device is not a valid block device, DeviceNotFound
-#
+# Returns: - Nothing on success
+#          - If @device is not a valid block device, DeviceNotFound
 # Notes:    Ejecting a device with no media results in success
 #
 # Since: 0.14.0
diff --git a/qapi/misc.json b/qapi/misc.json
index 626a342b008..06c80b58a24 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -418,12 +418,10 @@ 
 #
 # Return information about the balloon device.
 #
-# Returns: @BalloonInfo on success
-#
-#          If the balloon driver is enabled but not functional because the KVM
-#          kernel module cannot support it, KvmMissingCap
-#
-#          If no balloon device is present, DeviceNotActive
+# Returns: - @BalloonInfo on success
+#          - If the balloon driver is enabled but not functional because the KVM
+#            kernel module cannot support it, KvmMissingCap
+#          - If no balloon device is present, DeviceNotActive
 #
 # Since: 0.14.0
 #
@@ -480,8 +478,8 @@ 
 #
 # @bar: the index of the Base Address Register for this region
 #
-# @type: 'io' if the region is a PIO region
-#        'memory' if the region is a MMIO region
+# @type: - 'io' if the region is a PIO region
+#        - 'memory' if the region is a MMIO region
 #
 # @size: memory size
 #
@@ -992,10 +990,10 @@ 
 #
 # @value: the target size of the balloon in bytes
 #
-# Returns: Nothing on success
-#          If the balloon driver is enabled but not functional because the KVM
+# Returns: - Nothing on success
+#          - If the balloon driver is enabled but not functional because the KVM
 #            kernel module cannot support it, KvmMissingCap
-#          If no balloon device is present, DeviceNotActive
+#          - If no balloon device is present, DeviceNotActive
 #
 # Notes: This command just issues a request to the guest.  When it returns,
 #        the balloon size may not have changed.  A guest can change the balloon
@@ -1074,8 +1072,8 @@ 
 #       If @device is 'vnc' and @target is 'password', this is the new VNC
 #       password to set.  See change-vnc-password for additional notes.
 #
-# Returns: Nothing on success.
-#          If @device is not a valid block device, DeviceNotFound
+# Returns: - Nothing on success.
+#          - If @device is not a valid block device, DeviceNotFound
 #
 # Notes: This interface is deprecated, and it is strongly recommended that you
 #        avoid using it.  For changing block devices, use
@@ -1225,11 +1223,9 @@ 
 #
 # @opaque: A free-form string that can be used to describe the fd.
 #
-# Returns: @AddfdInfo on success
-#
-#          If file descriptor was not received, FdNotSupplied
-#
-#          If @fdset-id is a negative value, InvalidParameterValue
+# Returns: - @AddfdInfo on success
+#          - If file descriptor was not received, FdNotSupplied
+#          - If @fdset-id is a negative value, InvalidParameterValue
 #
 # Notes: The list of fd sets is shared by all monitor connections.
 #
@@ -1257,8 +1253,8 @@ 
 #
 # @fd: The file descriptor that is to be removed.
 #
-# Returns: Nothing on success
-#          If @fdset-id or @fd is not found, FdNotFound
+# Returns: - Nothing on success
+#          - If @fdset-id or @fd is not found, FdNotFound
 #
 # Since: 1.2.0
 #
diff --git a/qapi/tpm.json b/qapi/tpm.json
index 63878aa0f47..dc1f0817399 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -96,8 +96,8 @@ 
 #
 # A union referencing different TPM backend types' configuration options
 #
-# @type: 'passthrough' The configuration options for the TPM passthrough type
-#        'emulator' The configuration options for TPM emulator backend type
+# @type: - 'passthrough' The configuration options for the TPM passthrough type
+#        - 'emulator' The configuration options for TPM emulator backend type
 #
 # Since: 1.5
 ##