[02/13] docs/qapi: Document optional discriminators

Commit Message

Max Reitz May 9, 2018, 4:55 p.m. UTC

Signed-off-by: Max Reitz <[e-mail]>
---
 docs/devel/qapi-code-gen.txt | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

Comments

Eric Blake May 10, 2018, 1:14 p.m. UTC | #1

On 05/09/2018 11:55 AM, Max Reitz wrote:
> Signed-off-by: Max Reitz <[e-mail]>
> ---
>   docs/devel/qapi-code-gen.txt | 21 +++++++++++++++++++--
>   1 file changed, 19 insertions(+), 2 deletions(-)
> 

I might have squashed this in with patch 1, but I can live with it separate.

> @@ -502,6 +502,23 @@ the enum).  In the resulting generated C data types, a flat union is
>   represented as a struct with the base members included directly, and
>   then a union of structures for each branch of the struct.
>   
> +If the discriminator points to an optional member of the base struct,
> +its default value must be specified as a 'default-variant'.  In the
> +following example, the above BlockDriver struct is changed so it
> +defaults to the 'file' driver if that field is omitted on the wire:
> +
> + { 'union': 'BlockdevOptions',
> +   'base': { '*driver': 'BlockdevDriver', '*read-only': 'bool' },
> +   'discriminator': 'driver',
> +   'default-variant': 'file',
> +   'data': { 'file': 'BlockdevOptionsFile',
> +             'qcow2': 'BlockdevOptionsQcow2' } }
> +
> +Now the 'file' JSON object can be abbreviated to:
> +
> + { "read-only": "true",
> +   "filename": "/some/place/my-image" }
> +

Reviewed-by: Eric Blake <[e-mail]>

Patch

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index b9b6eabd08..35b9f0d99d 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -472,8 +472,8 @@  All branches of the union must be complex types, and the top-level
 members of the union dictionary on the wire will be combination of
 members from both the base type and the appropriate branch type (when
 merging two dictionaries, there must be no keys in common).  The
-'discriminator' member must be the name of a non-optional enum-typed
-member of the base struct.
+'discriminator' member must be the name of an enum-typed member of the
+base struct.
 
 The following example enhances the above simple union example by
 adding an optional common member 'read-only', renaming the
@@ -502,6 +502,23 @@  the enum).  In the resulting generated C data types, a flat union is
 represented as a struct with the base members included directly, and
 then a union of structures for each branch of the struct.
 
+If the discriminator points to an optional member of the base struct,
+its default value must be specified as a 'default-variant'.  In the
+following example, the above BlockDriver struct is changed so it
+defaults to the 'file' driver if that field is omitted on the wire:
+
+ { 'union': 'BlockdevOptions',
+   'base': { '*driver': 'BlockdevDriver', '*read-only': 'bool' },
+   'discriminator': 'driver',
+   'default-variant': 'file',
+   'data': { 'file': 'BlockdevOptionsFile',
+             'qcow2': 'BlockdevOptionsQcow2' } }
+
+Now the 'file' JSON object can be abbreviated to:
+
+ { "read-only": "true",
+   "filename": "/some/place/my-image" }
+
 A simple union can always be re-written as a flat union where the base
 class has a single member named 'type', and where each branch of the
 union has a struct with a single member named 'data'.  That is,