Re: [PATCH 3/4] qapi: remove trivial "Returns:" sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> The new qapidoc transmogrifier can generate "Returns" statements with
> type information just fine, so we can remove it from the source where it
> doesn't add anything particularly novel or helpful and just repeats the
> type info.
>
> This patch does not touch Returns: lines that add some information
> (potentially helpful, potentially not) but repeats the type information
> to remove that type.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

This is a clear improvement for the generated docs.  For instance,
blockdev-snapshot-delete-internal-sync goes from

    Return:
       "SnapshotInfo" -- SnapshotInfo

to

    Return:
       "SnapshotInfo"

However, I see that *triplicated* in my testing.  I observed similar
issues with the previous patch, so let's discuss that there and ignore
it here.

The impact on schema file egonomics is less clear.

This patch removes a bunch of "Returns:" sections that make the
generated docs look bad.  How can we stop people from writing such
sections?

Developers tend to refer to the schema file instead of the generated
documentation.  Information is spread across doc comment and schema
code.  Both describe the syntactic structure.  Only the schema code has
types, optional, and such.  The doc comment describes semantics.  In
practice, skimming the doc comment is often enough.

Except for the return value.  The doc comment's "Returns:" section is
optional.  When it's absent, the generated docs are bad (but this patch
fixes that).  Moreover, the doc comment doesn't fully describe the
syntactic structure then.  Unwary readers may not be aware of that trap,
and miss the return value.

The inliner you posted before needs to know where the inlined stuff
goes.  Obvious when there are argument descriptions or a "Returns:".
For the cases where we have nothing useful, you proposed an explicit
marker "Details:" (how exactly it's spelled doesn't matter here, only
that an explicit marker can be necessary).  Could removing "Returns:"
make the marker necessary more often?  Can our tooling reliably detect
the need for the marker?