On 03/09/2011 04:11 PM, Anthony Liguori wrote:
(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
Thanks. Something a little worrying is the reliance on capitalization
and punctuation ( {} vs [] ) do distinguish among the different types of
declarations. It's not immediately clear if something is a type, event,
or command.
We could do
[
{ 'type': 'MyType', fields: [['a', 'str'], ['b', 'int'], ['c',
'AnotherType']] }
{ 'event': 'MY_EVENT', 'arguments': [ ... ] }
{ 'command': 'my-command', 'arguments': [ ... ], 'return': ... }
]
which leaves us room for additional metainformation.
The concern is more about non-qemu consumers of the schema.
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 could add compatibility signatures when we extend a command:
{ 'command': 'x', arguments: [['a', 'str']], return: ...,
'signatures': { 'x': [], 'x2': ['a'] } }
That lets the wire protocol extend x without introducing a new command,
but for libqmp it adds a new x2() API with the new parameter.
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.
Agree.
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.
--
error compiling committee.c: too many arguments to function
