From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from [140.186.70.92] (port=42224 helo=eggs.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.43) id 1PzE0l-0006Dx-RX
	for qemu-devel@nongnu.org; Mon, 14 Mar 2011 16:06:46 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1PzE0b-00032b-8c
	for qemu-devel@nongnu.org; Mon, 14 Mar 2011 16:04:57 -0400
Received: from mail-yx0-f173.google.com ([209.85.213.173]:61013)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <anthony@codemonkey.ws>) id 1PzE0b-00032T-4w
	for qemu-devel@nongnu.org; Mon, 14 Mar 2011 16:04:53 -0400
Received: by yxk8 with SMTP id 8so2713002yxk.4
	for <qemu-devel@nongnu.org>; Mon, 14 Mar 2011 13:04:52 -0700 (PDT)
Message-ID: <4D7E74E1.30408@codemonkey.ws>
Date: Mon, 14 Mar 2011 15:04:49 -0500
From: Anthony Liguori <anthony@codemonkey.ws>
MIME-Version: 1.0
Subject: Re: [Qemu-devel] [RFC] QCFG: a new mechanism to replace QemuOpts
	and option handling
References: <4D7E5507.8010205@codemonkey.ws>
	<878vwhwkcq.fsf@ginnungagap.bsc.es>
In-Reply-To: <878vwhwkcq.fsf@ginnungagap.bsc.es>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 8bit
List-Id: qemu-devel.nongnu.org
List-Unsubscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <http://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: qemu-devel@nongnu.org

On 03/14/2011 02:52 PM, Lluís wrote:
> Anthony Liguori writes:
>
>> I've got a spec written up at http://wiki.qemu.org/Features/QCFG.  Initial code
>> is in my QAPI tree.
> What about moving the documentation to a 'doc' attribute?
>
> Thus, instead of the example vnconfig:
>
> { 'type': 'VncConfig',
>    'doc': 'Configuration options for the built-in VNC server.',
>    'data': {'address': 'str',
>             ...} }
>
> Still, it's not clear to me how attribute documentation shoul dbe
> provided:
>
>    'data': {'address': {'type': 'str',
>                         'doc': 'The hostname to bind the VNC server to...'},
>              ...
>            }
>
> Or maybe:
>
>    'data': {'address': 'str',
>             'address.doc': 'The hostname to bind the VNC server to...'},
>              ...
>            }
>
> But as I suppose these documentation comments are automatically
> processes, this might just prove too verbose for no benefit at all, as
> introspecting down to the documentation might be already doable with the
> format on the example.

Exactly.  This is the intention--to have the documentation be just as 
well structured as the JSON.

> You could also have a 'since' attribute, in case dynamic interface
> checks are necessary (e.g., the "Since: 0.14.0" in the example).

Indeed.

Regards,

Anthony Liguori

> Lluis
>
> --
>   "And it's much the same thing with knowledge, for whenever you learn
>   something new, the whole world becomes that much richer."
>   -- The Princess of Pure Reason, as told by Norton Juster in The Phantom
>   Tollbooth
>