On 03/28/2014 10:25 AM, Benoît Canet wrote:
> The new directive in the form { 'include': 'path/to/file.json' } will trigger the
> parsing of path/to/file.json.
> The directive will be replaced by the result of the parsing.
> 
> This will allow for easy modularisation of qapi JSON descriptions files.
> 
> Signed-off-by: Benoit Canet <benoit@irqsave.net>

Just noticed that your S-o-B is in plain ASCII, while your From: uses
Benoît.  Git handles UTF-8 names just fine, so you should feel welcome
to update your git config to use the same spelling in both places (of
course, since my own name doesn't have non-ASCII bytes, I don't quite
know the pain of getting my name munged by various tools...)

> +++ b/docs/qapi-code-gen.txt
> @@ -180,6 +180,20 @@ An example command is:
>     'data': { 'arg1': 'str', '*arg2': 'str' },
>     'returns': 'str' }
>  
> +=== Includes ===
> +
> +A schema file can include other sub schema files with the include
> +directive.
> +
> +An example of include directive is:
> +
> +{ 'include': 'path/to/sub_schema.json' }
> +
> +The include path is relative to the current schema file.
> +The include parsing method is recursive.
> +The expressions resulting from the parsing of the sub schema are injected
> +in place of the include directive like a C #include would do.
> +

Contrast to Lluís' version:

>
> +The QAPI schema definitions can be modularized using the 'include'
directive:
> +
> + { 'include': 'path/to/file.json'}
> +
> +Include paths are relative to the file using the directive.
> +
> +

I like that your version has an actual section on this (since you are
introducing a new top-level key, similar to existing top-level keys for
types, structs, unions, and Wenchao's work on events).  I also like your
explicit mention that include parsing is recursive (making it clear that
a sub-schema can also use include).  But I like Lluís wording better, in
part because it gets to the point in fewer words, and in part because
"relative to the file using the directive" is more precise than
"relative to the current schema file" (especially since the phrase
"injected in place of the include directive" made it fuzzy to me whether
the "current schema file" is the one specified on the command line after
contents have been injected).  Basically, I don't think the last
sentence, in comparing to a C #include, added any value.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org