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

[Luiz Capitulino <lcapitulino@redhat.com>]

On Sat, 15 May 2010 10:42:44 +0200
Jan Kiszka <jan.kiszka@web.de> wrote:

> Luiz Capitulino wrote:
> > 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.
> 
> Whatever its semantic is, technically it's a text block of a few lines
> that has to be added somewhere.
> 
> > 
> >  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).
> 
> I'm not talking about The Right solution, I'm talking about a more handy
> temporary setup. When do you plan to refactor the command documentation
> that way? And how many commands will be touched in the meantime?

 It's something we would like to do ASAP, but there are a number of things
we'll have to do first: bug fixes and some commands libvirt wants to use.

> >  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.
> > 
> 
> I can provide you the patch for hxtool and Makefile (a few lines), and
> I'm willing to split up the existing doc, just drop me a note. So
> nothing needs to be delayed any further.

 I'd love that.