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 <[email protected]> --- 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
