Re: [Qemu-devel] [RFC] QCFG: a new mechanism to replace QemuOpts and option handling

[Anthony Liguori]

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