[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate m
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings |
Date: |
Fri, 27 Mar 2015 12:02:51 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
Eric Blake <address@hidden> writes:
> QObject is an internal coding concept and requires the reader to
> reverse engineer the mapping; it is nicer to be explicit and call
> out specific JSON types.
>
> Signed-off-by: Eric Blake <address@hidden>
> ---
> docs/qapi-code-gen.txt | 24 ++++++++++++++----------
> 1 file changed, 14 insertions(+), 10 deletions(-)
>
> diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
> index 1f7d0ca..7fb0db7 100644
> --- a/docs/qapi-code-gen.txt
> +++ b/docs/qapi-code-gen.txt
> @@ -331,17 +331,21 @@ Resulting in this JSON object:
>
> Usage: { 'alternate: 'str', 'data': 'dict' }
>
> -An alternate type is one that allows a choice between two or more
> -QObject data types (string, integer, number, or dictionary, but not
> -array) on the wire. The definition is similar to a simple union type,
> -where each branch of the dictionary names a type, and where an
> -implicit C enum NameKind is created for the alternate Name. But
> +An alternate type is one that allows a choice between two or more JSON
> +data types on the wire. The definition is similar to a simple union
> +type, where each branch of the dictionary names a QAPI type, and where
> +an implicit C enum NameKind is created for the alternate Name. But
> unlike a union, the discriminator string is never passed on the wire
> -for QMP, instead appearing only in the generated C code. The type on
> -the wire serves an implicit discriminator, which in turn means that an
> -alternate can express a choice between a string and a single complex
> -type (passed as a dictionary), but cannot distinguish between two
> -different complex types. For example:
> +for QMP, instead appearing only in the generated C code. Rather, the
> +first byte of the value on the wire serves an implicit discriminator:
I think "first byte of" is implementation detail, and should be left
out.
> +if the branch is typed as the 'bool' built-in, it accepts true and
> +false; if it is typed as any of the various numeric built-ins, it
> +accepts a JSON number; if it is typed as a 'str' built-in or named
> +enum types it accepts a JSON string, and if it is typed as a named
> +struct or union type it accepts a JSON object. Thus, an alternate can
> +express a choice between a string and a single complex type (passed as
> +a dictionary), but cannot distinguish between two different complex
> +types or two different numeric built-in types. For example:
>
> { 'alternate': 'BlockRef',
> 'data': { 'definition': 'BlockdevOptions',
- [Qemu-devel] [PATCH 0/5] qapi doc cleanups, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings, Eric Blake, 2015/03/25
- Re: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings,
Markus Armbruster <=
- [Qemu-devel] [PATCH 5/5] qapi: Fix QMP spec references to JSON, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usage statements, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 1/5] qapi: Minor tweaks to qapi-code-gen.txt, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 4/5] qapi: Tweak doc references to QMP when QGA is also meant, Eric Blake, 2015/03/25
- Re: [Qemu-devel] [PATCH 0/5] qapi doc cleanups, Markus Armbruster, 2015/03/27