Skip to content

Commit

Permalink
qapi: Fix mangled "Returns" sections in documentation
Browse files Browse the repository at this point in the history
Commit e050e42 (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 a937b6a (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>
  • Loading branch information
Markus Armbruster committed Jan 26, 2024
1 parent 7cbdabb commit ae7ccd5
Show file tree
Hide file tree
Showing 3 changed files with 18 additions and 12 deletions.
15 changes: 9 additions & 6 deletions qapi/net.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
#
Expand All @@ -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:
#
Expand All @@ -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
#
Expand Down
5 changes: 3 additions & 2 deletions qapi/qdev.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 6 additions & 4 deletions qapi/qom.json
Original file line number Diff line number Diff line change
Expand Up @@ -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
#
Expand All @@ -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
#
Expand Down

0 comments on commit ae7ccd5

Please sign in to comment.