[Qemu-devel] Re: [PATCH 1/2] QMP: Introduce commands doc

[Luiz Capitulino <lcapitulino@redhat.com>]

On Fri, 14 May 2010 19:08:07 +0200
Jan Kiszka <jan.kiszka@siemens.com> wrote:

> Avi Kivity wrote:
> > On 05/14/2010 08:01 PM, Avi Kivity wrote:
> >> On 05/14/2010 07:52 PM, Jan Kiszka wrote:
> >>>> In order not to compromise QMP adoption and make users' life easier,
> >>>> this commit adds a simple text documentation which fully describes
> >>>> all QMP supported commands.
> >>>>
> >>>> This is not ideal for a number of reasons (harder to maintain,
> >>>> text-only, etc) but does improve the current situation.
> >>> Even if it's temporary - maintaining it in a separate file looks rather
> >>> unhandy.
> >>>
> >>> Can't we generate the per-command documentation snippets also from
> >>> qemu-monitor.hx and merge them with a header/footer into some text file?
> >>> That .hx file is the one anyone adding/converting commands has to touch
> >>> anyway.
> >> If we do, then the generated documentation should be included in the 
> >> patch changelog for review.
> >>
> > 
> > I mean, a patch introducing or modifying a monitor command.
> 
> The snippets should be readable by themselves. I'm only proposing to
> keep them in the central file, at the same location where the others
> are. There is no difference compared to existing monitor commands, we
> just add the third documentation snippet, this time for QMP.

 It's not only the snippets. We add a json type for each parameter, a
more descriptive info and notes. Only QMP commands should be shown
this way.

 I'm sure there's a way to hack the qemu's doc script to do all this,
but the right solution is to move _everything_ to json and generate good,
well formatted documentation from there (along with self-description).

 Also, adapting things will take time and this will delay even more this
doc to be merged, which is what I'm trying to avoid.