Re: [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> 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 <eblake@redhat.com>
> ---
>  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',