Re: [PATCH V2 1/5] qom: qom-tree-get

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> Steven Sistare <steven.sistare@oracle.com> writes:
>
>> On 7/4/2025 8:22 AM, Markus Armbruster wrote:
>>> Steve Sistare <steven.sistare@oracle.com> writes:
>>> 
>>>> Define the qom-tree-get QAPI command, which fetches an entire tree of
>>>> properties and values with a single QAPI call.  This is much faster
>>>> than using qom-list plus qom-get for every node and property of the
>>>> tree.  See qom.json for details.
>>>>
>>>> Signed-off-by: Steve Sistare <steven.sistare@oracle.com>
>>>> ---
>>>>   qapi/qom.json      | 56 ++++++++++++++++++++++++++++++++++++++++++
>>>>   qom/qom-qmp-cmds.c | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>>   2 files changed, 128 insertions(+)
>>>>
>>>> diff --git a/qapi/qom.json b/qapi/qom.json
>>>> index 28ce24c..94662ad 100644
>>>> --- a/qapi/qom.json
>>>> +++ b/qapi/qom.json

[...]

>>>> ##
>>>> +# @qom-tree-get:
>>>> +#
>>>> +# This command returns a tree of objects and their properties,
>>>> +# rooted at the specified path.
>>>> +#
>>>> +# @path: The absolute or partial path within the object model, as
>>>> +#     described in @qom-get
>>>> +#
>>>> +# Errors:
>>>> +#     - If path is not valid or is ambiguous, returns an error.
>>> 
>>> By convention, we use "If <condition>, <error>, where <error> is a
>>> member of QapiErrorClass.
>>
>> OK.  I was following the minimal Errors examples from this same file.
>
> Yup.  I'll clean them up.

I changed my mind.

Omitting ", <error>" is fairly common, actually.  I don't feel like
chasing down the actual error classes.  Moreover, documenting error
classes we don't want people to use seems counterproductive.

Feel free to just delete ", returns an error." and call it a day.

[...]