Luiz Capitulino <lcapitul...@redhat.com> writes:
> On Tue, 29 Dec 2009 19:25:24 +0000
> Nathan Baum <nat...@parenthephobia.org.uk> wrote:
>
>> On Tue, 2009-12-29 at 15:15 -0200, Luiz Capitulino wrote:
>> > On Sat, 26 Dec 2009 21:19:22 +0000
>> > Nathan Baum <nat...@parenthephobia.org.uk> wrote:
>> >
>> > > Signed-off-by: Nathan Baum <nat...@parenthephobia.org.uk>
>> > > ---
>> > > hw/qdev.c | 9 ++++++++-
>> > > hw/qdev.h | 3 ++-
>> > > monitor.c | 3 ++-
>> > > 3 files changed, 12 insertions(+), 3 deletions(-)
>> > >
>> > > diff --git a/hw/qdev.c b/hw/qdev.c
>> > > index f5d68c6..d9d3778 100644
>> > > --- a/hw/qdev.c
>> > > +++ b/hw/qdev.c
>> > > @@ -727,6 +727,12 @@ static void do_info_qbus(Monitor *mon, BusState
>> > > *bus, QObject **ret_data)
>> > > *ret_data = (QObject *) qdict;
>> > > }
>> > >
>> > > +void do_info_qtree(Monitor *mon, QObject **ret_data)
>> > > +{
>> > > + if (main_system_bus)
>> > > + do_info_qbus(mon, main_system_bus, ret_data);
>> > > +}
>> > > +
>> >
>> > What I'm missing here is a high-level documentation of the
>> > data type you're building.
>>
>> Oh yes. I didn't think about that!
>>
>> I'm not sure if there's a policy on how complicated QMP responses will
>> be documented?
>
> No. Markus and I have just started talking about a documentation format
> for QMP.
That was just before Christmas, and that's why I haven't gotten around
to posting it here properly.
> Markus, it's time to dump your ideas on the list.
Indeed. I'm working on it, and hope get it posted today.
>> One possibility that seems quite nice is to use something like JSON
>> Schema[1], which describes JSON objects using JSON, since that means QMP
>> clients can ask Qemu itself to describe its own protocol, and the result
>> could be automatically processed (with some hypothetical "qmpdoc" tool)
>> to produce human-readable documentation.
>
> This looks very good!
It does. Thanks for the pointer!
> We were considering something along these lines
> but we didn't consider having the description as part of the dict,
> for example.
We did, actually :)
> This solves some issues we were trying to address.
>
> The only problem I can see is that the documentation and code will
> be in different places, which makes it easier to get outdated.
Not necessarily. Documentation will be in whatever place we put it.
Some places require tools to extract it.
[...]
