Re: [PATCH v6 4/4] qapi: rephrase return docs to avoid type name

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Well, I tried. Maybe not very hard. Sorry!

Recommend to explain *why* we want to avoid the type name.

  "Returns: <description>" is rendered like "Return: <Type> –
  <description>".  Mentioning the type in the description again is
  commonly redundant.  Rephrase such descriptions not to.

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json   | 6 +++---
>  qapi/block-export.json | 2 +-
>  qapi/block.json        | 2 +-
>  qapi/control.json      | 5 ++---
>  qapi/dump.json         | 5 ++---
>  qapi/introspect.json   | 6 +++---
>  qapi/job.json          | 2 +-
>  qapi/misc-i386.json    | 2 +-
>  qapi/misc.json         | 5 ++---
>  qapi/net.json          | 2 +-
>  qapi/pci.json          | 2 +-
>  qapi/qdev.json         | 3 +--
>  qapi/qom.json          | 8 +++-----
>  qapi/stats.json        | 2 +-
>  qapi/trace.json        | 2 +-
>  qapi/ui.json           | 2 +-
>  qapi/virtio.json       | 6 +++---
>  17 files changed, 28 insertions(+), 34 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index d64f482d9bd..f18db3149a3 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -763,7 +763,7 @@
>  #
>  # Get a list of BlockInfo for all virtual block devices.

Mentioning the type in the intro is commonly just as redundant as in
Returns:.

>  #
> -# Returns: a list of @BlockInfo describing each virtual block device.
> +# Returns: a list describing each virtual block device.

"A list" is arguably just as redundant as the list's element type.

The entire line is pretty redundant with the intro.

>  #     Filter nodes that were created implicitly are skipped over.
>  #
>  # Since: 0.14
> @@ -1168,7 +1168,7 @@
   ##
   # @query-blockstats:
   #
   # Query the `BlockStats` for all virtual block devices.
   #
   # @query-nodes: If true, the command will query all the block nodes
   #     that have a node name, in a list which will include "parent"
   #     information, but not "backing".  If false or omitted, the
   #     behavior is as before - query all the device backends,
   #     recursively including their "parent" and "backing".  Filter
>  #     nodes that were created implicitly are skipped over in this
>  #     mode.  (Since 2.3)
>  #
> -# Returns: A list of @BlockStats for each virtual block devices.
> +# Returns: A list of statistics for each virtual block device.

Again, the entire line is pretty redundant with the intro.

>  #
>  # Since: 0.14
>  #
> @@ -1440,7 +1440,7 @@
>  #
>  # Return information about long-running block device operations.
>  #
> -# Returns: a list of @BlockJobInfo for each active block job
> +# Returns: a list of job info for each active block job

Best not to abbreviate "information" to "info".

>  #
>  # Since: 1.1
>  ##

I need to stop here to take care of another series.  Gut feeling so far:
right direction, doesn't go far enough.

Choices:

* Go far enough.  Too close to the freeze for that, I'm afraid.

* Merge it basically as is, come back later to finish the job.

* Drop it for now, adjust your "QAPI: add cross-references to qapi docs"
  to enclose the type names not removed in `backquotes`.

Thoughts?

[...]