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. 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.
