[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH RFC] qapi: Allow getting flat output from 'query-named-block-
From: |
Markus Armbruster |
Subject: |
Re: [PATCH RFC] qapi: Allow getting flat output from 'query-named-block-nodes' |
Date: |
Tue, 17 Dec 2019 16:11:37 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) |
Eric Blake <address@hidden> 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.