qapi: Fix mangled "Returns" sections in documentation

Commit e050e426782e (qapi: Use explicit bulleted lists) added list
markup to correct bad rendering:

    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.

It missed a few instances.  Commit a937b6aa739 (qapi: Reformat doc
comments to conform to current conventions) then reflowed them.

Revert the reflowing, and add list markup.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240120095327.666239-6-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>

diff --git a/qapi/net.json b/qapi/net.json
index 8095b68fa831f0f310b515903c9fbe64b028d741..68493d6ac9892d1c0baf78f6a8abeef9e88b3628 100644 (file)
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -18,8 +18,9 @@
 #
 # @up: true to set the link status to be up
 #
-# Returns: Nothing on success If @name is not a valid network device,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @name is not a valid network device, DeviceNotFound
 #
 # Since: 0.14
 #
@@ -44,8 +45,9 @@
 #
 # Since: 0.14
 #
-# Returns: Nothing on success If @type is not a valid network backend,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @type is not a valid network backend, DeviceNotFound
 #
 # Example:
 #
@@ -64,8 +66,9 @@
 #
 # @id: the name of the network backend to remove
 #
-# Returns: Nothing on success If @id is not a valid network backend,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @id is not a valid network backend, DeviceNotFound
 #
 # Since: 0.14
 #

diff --git a/qapi/qdev.json b/qapi/qdev.json
index 6bc5a733b86f1cff5b060fb88161ba3e17513b85..25bac5e61153b462604f4ea3b996cc008273f456 100644 (file)
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -89,8 +89,9 @@
 #
 # @id: the device's ID or QOM path
 #
-# Returns: Nothing on success If @id is not a valid device,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @id is not a valid device, DeviceNotFound
 #
 # Notes: When this command completes, the device may not be removed
 #     from the guest.  Hot removal is an operation that requires guest

diff --git a/qapi/qom.json b/qapi/qom.json
index 95516ba325e541e5eeb3e1f588474cdf63ad68a5..84af23fe245de777985de1a67afbffdde92bfca7 100644 (file)
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1056,8 +1056,9 @@
 #
 # Create a QOM object.
 #
-# Returns: Nothing on success Error if @qom-type is not a valid class
-#     name
+# Returns:
+#     - Nothing on success
+#     - Error if @qom-type is not a valid class name
 #
 # Since: 2.0
 #
@@ -1078,8 +1079,9 @@
 #
 # @id: the name of the QOM object to remove
 #
-# Returns: Nothing on success Error if @id is not a valid id for a QOM
-#     object
+# Returns:
+#     - Nothing on success
+#     - Error if @id is not a valid id for a QOM object
 #
 # Since: 2.0
 #