Re: [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerations

[Eric Blake <eblake@redhat.com>]

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

On 04/04/2015 10:07 PM, Eric Blake wrote:
> Go into more details about the various types of valid expressions
> in a qapi schema, including tweaks to document fixes being done
> later in the current patch series.  Also fix some stale and missing
> documentation in the QMP specification.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>
> 
> ---
> 
> v6: split copyright change into another patch; merge in 1/5, 3/5,
> and 5/5 of doc cleanup series; drop simple union with base docs,
> and mention relation between simple and flat unions; mention QMP
> is encoded as UTF-8; mention extensions of 'single \' quote' and
> "\'"; mention that repeating json-object (dict) keys is unspecified.

A bit of self-review:

> +++ b/docs/qmp/qmp-spec.txt
> @@ -13,8 +13,11 @@ Last revised in March 2015.
> @@ -62,7 +78,19 @@ The greeting message format is:
>  - The "version" member contains the Server's version information (the format
>    is the same of the query-version command)
>  - The "capabilities" member specify the availability of features beyond the
> -  baseline specification
> +  baseline specification; the order of elements in this array has no
> +  particular significance, so a client must search the entire array
> +  when looking for a particular capability
> +
> +When first connecting to the server, the connection is in a capability
> +exchange mode, further documented below.

This sentence is redundant with the earlier sentence in the same section:

>> Right when connected the Server will issue a greeting message, which signals
>> that the connection has been successfully established and that the Server is
>> ready for capabilities negotiation (for more information refer to section
>> '4. Capabilities Negotiation').

I'll wait for other reviews before deciding whether it is easier to do
as a patch that a maintainer squashes in on commit of v6, as a v7
respin, or as an independent followup patch.

>  4. Capabilities Negotiation
> -----------------------------
> +===========================
> 
>  When a Client successfully establishes a connection, the Server is in
>  Capabilities Negotiation mode.

Meanwhile, as this has just come up on the list, I'm now looking at how
easy it would be to make capability negotiation give saner error messages :)
https://lists.gnu.org/archive/html/qemu-devel/2015-04/msg00833.html

Which of course may mean further touching of this file, and therefore
justifying a separate cleanup patch anyways.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]