Re: [Qemu-devel] [PATCH v3 31/50] docs: document schema configuration

[Markus Armbruster]

Cc: Eric for an additional pair of eyeballs.

Marc-André Lureau <address@hidden> writes:

> Signed-off-by: Marc-André Lureau <address@hidden>
> ---
>  docs/devel/qapi-code-gen.txt | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index 0a90f2278a..24fc6f74ee 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -682,6 +682,43 @@ Example: Red Hat, Inc. controls redhat.com, and may 
> therefore add a
>  downstream command __com.redhat_drive-mirror.
>  
>  
> +=== Configuring the schema ===
> +
> +'struct', 'enum', 'union', 'alternate', 'command' and 'event'
> +top-level QAPI expressions can take a 'if' keyword like:

an 'if' key

> +
> +{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },
> +  'if': 'defined(IF_STRUCT) && defined(FOO)' }

Perhaps we should add something like

    Code generated for such conditional definitions will be guarded with
    #if IFCOND, where IFCOND is the value of the 'if' key.

> +
> +Members can be exploded as dictionnary with 'type' & 'if' keys:

dictionary

I get what you mean by "can be exploded", but can we phrase this more
clearly?

In section "Struct types", we have

    A struct is a dictionary containing a single 'data' key whose value is
    a dictionary; the dictionary may be empty.  This corresponds to a
    struct in C or an Object in JSON. Each value of the 'data' dictionary
    must be the name of a type, or a one-element array containing a type
    name.

The part "must be the name of a type, or a one-element array containing
a type" name is now wrong.

Likewise, in section "Enumeration types"

    An enumeration type is a dictionary containing a single 'data' key
    whose value is a list of strings.

> +
> +{ 'struct': 'IfStruct', 'data':
> +  { 'foo': 'int',
> +    'bar': { 'type': 'int', 'if': 'defined(IF_STRUCT_BAR)'} } }

Perhaps add something like

    Code generated for such conditional members will be guarded with #if
    IFCOND, where IFCOND is the value of the 'if' key.

> +
> +Enum values can be exploded as dictionnary with 'name' & 'if' keys:

dictionnary and exploded again.

> +
> +{ 'enum': 'IfEnum', 'data':
> +  [ 'foo',
> +    { 'name' : 'bar', 'if': 'defined(IF_ENUM_BAR)' } ] }
> +
> +The C code generators will wrap the corresponding lines with #if / #endif
> +pre-processor conditions for a given 'if' value.
> +
> +Example for enum values:
> +
> +enum IfEnum {
> +     IF_ENUM_FOO,
> +#if defined(IF_ENUM_BAR)
> +     IF_ENUM_BAR,
> +#endif /* defined(IF_ENUM_BAR) */
> +     IF_ENUM__MAX
> +}

Hmm.  If enumeration documentation profits from an example, it stands to
reason that the previous two would, too.

Should we (additionally?) add examples of 'if' in section "Code
generation"?

> +
> +Please note that you are responsbile to ensure that the C code will
> +compile with an arbitrary combination of conditions, since the
> +generators are unable to check it at this point.
> +
>  == Client JSON Protocol introspection ==
>  
>  Clients of a Client JSON Protocol commonly need to figure out what

Do we need to update section "Client JSON Protocol introspection"?