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

[Eric Blake]

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:
+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',
-- 
2.1.0