[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappi
From: |
Eric Blake |
Subject: |
[Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings |
Date: |
Wed, 25 Mar 2015 18:13:54 -0600 |
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
- [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 <=
- [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