Re: [Qemu-devel] [PATCH 1/1] QAPI schema: turn example commands/returns into proper JSON

[Eric Blake]

On 08/08/2017 03:53 PM, Cleber Rosa wrote:
> Most QMP commands and returns in the QAPI schema documentation
> are valid "JSON-based wire format".  A few examples are either
> malformed, or contain comments.
> 
> This fixes all the examples command and return data, making them
> proper JSON, as they would be received and generated by QEMU's
> QMP monitor.
> 
> Signed-off-by: Cleber Rosa <address@hidden>
> ---
>  qapi-schema.json     |  9 ++++-----
>  qapi/block-core.json | 32 ++++++++++++++++----------------
>  qapi/rocker.json     |  5 +----
>  3 files changed, 21 insertions(+), 25 deletions(-)


> +++ b/qapi-schema.json
> @@ -2000,8 +2000,7 @@
>  #                "host": "127.0.0.1",
>  #                "channel-id": 0,
>  #                "tls": false
> -#             },
> -#             [ ... more channels follow ... ]
> +#             }

I still wonder if we want SOME sort of markup to make it obvious where
we are compressing the example for the sake of brevity, where whatever
we use to automate tests based on the docs would know how to recognize
that the actual values given in reply to the test can be longer than the
documented example.  But I guess we can cross that when we have an
automated test where it matters.

> @@ -2039,7 +2038,7 @@
>  #
>  # -> { "execute": "query-balloon" }
>  # <- { "return": {
> -#          "actual": 1073741824,
> +#          "actual": 1073741824
>  #       }

I also suspect that test automation will have to do a lot of filtering,
even for commands that don't need to be abbreviated, since some of the
examples have pretty arbitrary numbers that will be difficult to
reliably reproduce any particular number.

This is a documentation fix, so it could still go in 2.10 - but since we
are past -rc2, it's probably just as easy to save it for 2.11.  Either way,

Reviewed-by: Eric Blake <address@hidden>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature