Re: [PATCH RFC] qapi: Allow getting flat output from 'query-named-block-nodes'

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> On 12/17/19 1:36 AM, Markus Armbruster wrote:
>
>> Un-snipping the QAPI schema change:
>
> Sorry about that...
>
>>
>>>> diff --git a/qapi/block-core.json b/qapi/block-core.json
>>>> index 0cf68fea14..bd651106bd 100644
>>>> --- a/qapi/block-core.json
>>>> +++ b/qapi/block-core.json
>>>> @@ -1752,6 +1752,8 @@
>>>>   #
>>>>   # Get the named block driver list
>>>>   #
>>>> +# @flat: don't recurse into backing images if true. Default is false (Since 5.0)
>>>> +#
>>>>   # Returns: the list of BlockDeviceInfo
>>>>   #
>>>>   # Since: 2.0
>>
>> What does it mean not to recurse?  Sounds like flat: false asks for a
>> subset of the full set.  How exactly is the subset defined?
>
> Bike-shedding:
>
> Would it be easier to explain as:
>
> @recurse: If true, include child information in each node (note that
> this can result in redundant output). Default is true (since 5.0)
>
> and then pass false when you don't want recursion, with it being more
> obvious that using the new flag results in more compact output with no
> loss of information.

Adds a bit of information, namely that the information suppressed by
recurse: false is actually redundant.

The command's doc comment is weak: it doesn't really specify what
exactly is returned.  Simply omitting redundant information always
should still conform to this weak spec.  Of course, what really counts
isn't spec conformance, but meeting client expectations.  I don't even
understand what exactly gets returned, let alone how clients use it.

The doc comment needs to be judged by someone with actual knowledge in
this area.