[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerati
From: |
Eric Blake |
Subject: |
Re: [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerations |
Date: |
Wed, 08 Apr 2015 10:50:48 -0600 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.6.0 |
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 <address@hidden>
>
> ---
>
> 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
signature.asc
Description: OpenPGP digital signature
- [Qemu-devel] [PATCH v6 05/36] qapi: Require ASCII in schema, (continued)
- [Qemu-devel] [PATCH v6 05/36] qapi: Require ASCII in schema, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 12/36] qapi: Prepare for catching more semantic parse errors, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 07/36] qapi: Better error messages for bad enums, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 09/36] qapi: Clean up test coverage of simple unions, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 06/36] qapi: Add some enum tests, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 10/36] qapi: Forbid base without discriminator in unions, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 02/36] qapi: Document type-safety considerations, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 15/36] qapi: Document new 'alternate' meta-type, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 13/36] qapi: Segregate anonymous unions into alternates in generator, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 14/36] qapi: Rename anonymous union type in test, Eric Blake, 2015/04/05
- [Qemu-devel] [PATCH v6 11/36] qapi: Tighten checking of unions, Eric Blake, 2015/04/05