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

[Markus Armbruster]

Stefan Hajnoczi <address@hidden> writes:

> 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 <address@hidden>
>> >Signed-off-by: Stefan Hajnoczi <address@hidden>
>> >---
>> >  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.

qmp-commands.hx needs to go.  A few things keep it around, and one of
them is qemu-commands.txt.  Need to generate a satisfactory replacement
from the QAPI schema.