From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=43252 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PxK7B-0003XJ-08 for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:11:50 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PxK79-0006tE-JQ for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:11:48 -0500 Received: from mail-iy0-f173.google.com ([209.85.210.173]:51285) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PxK79-0006t4-Cu for qemu-devel@nongnu.org; Wed, 09 Mar 2011 09:11:47 -0500 Received: by iym7 with SMTP id 7so649207iym.4 for ; Wed, 09 Mar 2011 06:11:46 -0800 (PST) Message-ID: <4D778A9F.80700@codemonkey.ws> Date: Wed, 09 Mar 2011 08:11:43 -0600 From: Anthony Liguori MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH 14/22] qapi: add query-version QMP command References: <1299460984-15849-1-git-send-email-aliguori@us.ibm.com> <1299460984-15849-15-git-send-email-aliguori@us.ibm.com> <4D778246.8090504@redhat.com> In-Reply-To: <4D778246.8090504@redhat.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Avi Kivity Cc: qemu-devel@nongnu.org, Adam Litke , Anthony Liguori , Markus Armbruster , Luiz Capitulino 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