Re: [Qemu-devel] [PATCH] block: document block-stream in qmp-commands.hx

[Stefan Hajnoczi <stefanha@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2278 bytes --]

On Wed, Apr 15, 2015 at 03:08:30PM +0200, Max Reitz wrote:
> On 15.04.2015 12:43, Stefan Hajnoczi wrote:
> >The 'block-stream' QMP command is documented in block-core.json but not
> >qmp-commands.hx.  Add a summary of the command to qmp-commands.hx
> >(similar to the documentation for 'block-commit').
> >
> >Reported-by: Kashyap Chamarthy <kchamart@redhat.com>
> >Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> >---
> >  qmp-commands.hx | 37 +++++++++++++++++++++++++++++++++++++
> >  1 file changed, 37 insertions(+)
> >
> >diff --git a/qmp-commands.hx b/qmp-commands.hx
> >index 3a42ad0..7a745ed 100644
> >--- a/qmp-commands.hx
> >+++ b/qmp-commands.hx
> >@@ -1008,6 +1008,43 @@ EQMP
> >          .mhandler.cmd_new = qmp_marshal_input_block_stream,
> >      },
> >+SQMP
> >+block-stream
> >+------------
> >+
> >+Copy data from a backing file into a block device.
> 
> It looks like you stopped just copy-pasting the information from
> block-core.json here...
> 
> >+
> >+Arguments:
> >+
> >+- "device": The device's ID, must be unique (json-string)
> 
> ...instead sometimes copying it from block-commit...
> 
> >+- "base": The file name of the backing image above which copying starts
> >+          (json-string, optional)
> 
> ...or creating new descriptions...
> 
> >+- "backing-file": The backing file string to write into the active layer. This
> >+                  filename is not validated.
> 
> ...and then you are continuing copying the block-core.json entry.
> 
> Is there a reason why you didn't just take all of the block-core.json
> comment and put it here? (just curious)

Yes.  block-commit has a similar approach where the qmp-commands.hx
doesn't contain the full command description, just a summary.

Unfortunately, the QAPI schema and QMP argument descriptions differ.
They use different conventions so I needed to adapt or rewrite them.
The path I chose was a mixture of a little bit from, a little bit from
there, and some of my own magic :P.

The best long-term step would be to pick a canonical documentation unit
- either QAPI schema or qmp-commands - and resolve differences between
them.  Then we'll have just 1 location and all documentation can be
generated from it.

Stefan

[-- Attachment #2: Type: application/pgp-signature, Size: 473 bytes --]