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

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Fri, Mar 28, 2025 at 4:36 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Well, I tried. Maybe not very hard. Sorry!
>>
>> No need to be sorry!  Kick-starting discussion with limited effort is
>> better than a big effort going into a direction that turns out to be
>> unwanted once we discuss it.
>>
>> Instead of just rephrasing Returns descriptions, I'd like us to consider
>> both Returns and intro.  See below for why.

[...]

> I think for cases where the doc block is short and we have a desire to
> merge "returns" and "intro", the intro makes the most sense if there isn't
> anything of particular value assigned to the return value to begin with.
>
> So, more or less, yeah: if semantics are partially duplicated between
> intro/returns, I'm in favor of putting it all in the intro and allowing
> transmogrifier generate the return type info.
>
> I don't think there's a good case to make for a doc block with no intro but
> a healthy paragraph in the returns section, that looks goofy.
>
> Of course: I think there are still circumstances where we'll want both the
> intro and the returns info explicitly labeled, when we have some
> information to document about the semantics of that return value.

Agreed.

[...]