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
