Re: [Qemu-devel] [PATCH v6 22/27] docs: document schema configuration

[Markus Armbruster <armbru@redhat.com>]

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

> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> ---
>  docs/devel/qapi-code-gen.txt | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index c2e11465f0..799aef7728 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -752,6 +752,25 @@ gets its generated code guarded like this:
>   #endif /* defined(HAVE_BAR) */
>   #endif /* defined(CONFIG_FOO) */
>  
> +Where a member can be defined with a single string value for its type,
> +it is also possible to supply a dictionary instead with both 'type'
> +and 'if' keys.
> +
> +Example: a conditional 'bar' member
> +
> +{ 'struct': 'IfStruct', 'data':
> +  { 'foo': 'int',
> +    'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
> +
> +An enum value can be replaced by a dictionary with a 'name' and a 'if'
> +key.
> +
> +Example: a conditional 'bar' enum member.
> +
> +{ 'enum': 'IfEnum', 'data':
> +  [ 'foo',
> +    { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
> +
>  Please note that you are responsible 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.

I'd prefer to update qapi-code-gen.txt right when we extend the schema
language, like you did in part 1 (commit 967c885108f qapi: add 'if' to
top-level expressions).  I understand it's a bit more churn, since you
need four steps (enum, struct, union, alternate members).  I think the
following would be the least work for you that still satisfies me:

* Add the part about enum values in PATCH 13.

* Add the rest in PATCH 17 (the first patch that implements a part of
  it), with a TODO implement <list of things that get done in later
  patches>.  Then just update the TODO as you go.

Okay?