Re: [Qemu-devel] [PATCH 14/22] qapi: add query-version QMP command

[Anthony Liguori <anthony@codemonkey.ws>]

On 03/09/2011 07:36 AM, Avi Kivity wrote:
> On 03/07/2011 03:22 AM, Anthony Liguori wrote:
>> This is used internally by QMP.  It's also a pretty good example of a 
>> typical
>> command conversion.
>>
>> +##
>> +{ 'VersionInfo': {'qemu': {'major': 'int', 'minor': 'int', 'micro': 
>> 'int'},
>> +                  'package': 'str'} }
>> +
>> +##
>> +# @query-version:
>> +#
>> +# Returns the current version of QEMU.
>> +#
>> +# Returns:  A @VersionInfo object describing the current version of 
>> QEMU.
>> +#
>> +# Since: 0.14.0
>> +##
>> +[ 'query-version', {}, {}, 'VersionInfo' ]
>
> (just picking on a patch that has a bit of schema in it)

If you want to see more of the schema in action 
http://repo.or.cz/w/qemu/aliguori.git/blob/refs/heads/glib:/qmp-schema.json

> Something that can be added to the schema are default values for newly 
> added parameters.  This way we can avoid an explosion of commands 
> where adding an optional parameter suffices; should be easier for the 
> user to pick the right command and easier for us to document and support.

Adding a parameter to a command, even if the schema specifies a default 
value, is going to break the C library ABI so it's something we should 
strongly discourage.

We definitely want to systematically document defaults but the question 
is whether that belongs in the documentation for the command or the 
schema itself.  Since a default doesn't affect the wire protocol in any 
way, shape, or form, I think there a pretty strong argument that it 
belongs in the documentation and not the schema.

gtk-doc typically uses a tag to identify defaults.  I think it's 
something like #default although that is purely a marking concept (the 
value isn't parsed out or anything).  Whether we'd want to automatically 
parse the value following the #default tag and change the internal 
signature is probably a discussion we can defer.  Since this only really 
should apply to structures, I suspect it's not a huge win.

Regards,

Anthony Liguori