[v3,31/50] docs: document schema configuration

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
---
 docs/devel/qapi-code-gen.txt | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

Cc: Eric for an additional pair of eyeballs.

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  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"?

On 12/13/2017 04:41 AM, Markus Armbruster wrote:
> Cc: Eric for an additional pair of eyeballs.
> 
> Marc-André Lureau <marcandre.lureau@redhat.com> writes:
> 
>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>> ---
>> +
>> +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.

Maybe:

Where a member can normally be defined with a single string value as its
type, it is also possible to supply a dictionary with both 'type' and
'if' keys.  The generated code will then guard the inclusion of that
member in the larger struct or command with #if IFCOND, where IFCOND is
the value of the 'if' key.

>> +
>> +{ '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.
> 

> 
> 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"?

It makes the examples longer, but may be worthwhile.

> 
>> +
>> +Please note that you are responsbile to ensure that the C code will

s/responsbile/responsible/

>> +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"?

It doesn't affect what the client can do with what it introspects, but
may indeed be worth mentioning that the presence of 'if' keys in the
schema is reflected through to the introspection output.