Eric Blake <ebl...@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.
