Luiz Capitulino wrote: > On Fri, 14 May 2010 19:08:07 +0200 > Jan Kiszka <jan.kis...@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? > > 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. Jan
signature.asc
Description: OpenPGP digital signature
