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

[Eric Blake]

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

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature