John Snow <js...@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 <js...@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? [...]
