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

[Avi Kivity]

On 05/14/2010 08:08 PM, Jan Kiszka wrote:
> > I mean, a patch introducing or modifying a monitor command.
> >      
> The snippets should be readable by themselves.

They may be readable, but that doesn't mean anyone will read them.  It's 
a lot easier for someone who isn't involved in the code (the libvirt 
people, or me) to review standalone documentation than something 
embedded in a patch (typically at the very end).

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

That's fine.  But the fact that a lot of review comments pointing out 
issues surface only now show that we need to make things easier for 
reviewers.  It's much harder to fix an external interface than an 
internal one.

> Distributing a generated QMP/qmp-commands.txt is another thing, maybe a
> useful one.
>    

Sure, like the other qemu documentation.

--
Do not meddle in the internals of kernels, for they are subtle and quick to 
panic.