docs: Document QAPI union types

There are two basic syntaxes used, type definitions and command definitions.

The first syntax defines a type and is represented by a dictionary.  There are

two kinds of types that are supported: complex user-defined types, and enums.

three kinds of user-defined types that are supported: complex types,

enumeration types and union types.

A complex type is a dictionary containing a single key who's value is a

Generally speaking, types definitions should always use CamelCase for the type

names. Command names should be all lower case with words separated by a hyphen.

=== Complex types ===

A complex type is a dictionary containing a single key whose value is a

dictionary.  This corresponds to a struct in C or an Object in JSON.  An

example of a complex type is:

members should always be added to the end of the dictionary to preserve

backwards compatibility.

An enumeration type is a dictionary containing a single key who's value is a

=== Enumeration types ===

An enumeration type is a dictionary containing a single key whose value is a

list of strings.  An example enumeration is:

 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }

Generally speaking, complex types and enums should always use CamelCase for

the type names.

=== Union types ===

Union types are used to let the user choose between several different data

types.  A union type is defined using a dictionary as explained in the

following paragraphs.

A simple union type defines a mapping from discriminator values to data types

like in this example:

 { 'type': 'FileOptions', 'data': { 'filename': 'str' } }

 { 'type': 'Qcow2Options',

   'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }

 { 'union': 'BlockdevOptions',

   'data': { 'file': 'FileOptions',

             'qcow2': 'Qcow2Options' } }

In the QMP wire format, a simple union is represented by a dictionary that

contains the 'type' field as a discriminator, and a 'data' field that is of the

specified data type corresponding to the discriminator value:

 { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",

                               "lazy-refcounts": true } }

A union definition can specify a complex type as its base. In this case, the

fields of the complex type are included as top-level fields of the union

dictionary in the QMP wire format. An example definition is:

 { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }

 { 'union': 'BlockdevOptions',

   'base': 'BlockdevCommonOptions',

   'data': { 'raw': 'RawOptions',

             'qcow2': 'Qcow2Options' } }

And it looks like this on the wire:

 { "type": "qcow2",

   "readonly": false,

   "data" : { "backing-file": "/some/place/my-image",

              "lazy-refcounts": true } }

=== Commands ===

Commands are defined by using a list containing three members.  The first

member is the command name, the second member is a dictionary containing

   'data': { 'arg1': 'str', '*arg2': 'str' },

   'returns': 'str' }

Command names should be all lower case with words separated by a hyphen.

== Code generation ==