marcandre.lur...@redhat.com writes:
> From: Marc-André Lureau <marcandre.lur...@redhat.com>
>
> Signed-off-by: Marc-André Lureau <marcandre.lur...@redhat.com>
> Reviewed-by: Stefan Hajnoczi <stefa...@redhat.com>
> Tested-by: John Snow <js...@redhat.com>
> ---
> docs/devel/qapi-code-gen.txt | 27 ++++++++++++++++-----------
> 1 file changed, 16 insertions(+), 11 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index edaaf7ec40..4a3fd02723 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -780,26 +780,31 @@ downstream command __com.redhat_drive-mirror.
> === Configuring the schema ===
>
> Syntax:
> - COND = STRING
> - | [ STRING, ... ]
> + COND = CFG-ID
> + | [ COND, ... ]
> + | { 'all: [ COND, ... ] }
> + | { 'any: [ COND, ... ] }
> + | { 'not': COND }
>
> -All definitions take an optional 'if' member. Its value must be a
> -string or a list of strings. A string is shorthand for a list
> -containing just that string. The code generated for the definition
> -will then be guarded by #if STRING for each STRING in the COND list.
> + CFG-ID = STRING
> +
> +All definitions take an optional 'if' member. Its value must be a string, a
> list
> +of strings or an object with a single member 'all', 'any' or 'not'. A string
> is
> +shorthand for a list containing just that string. A list is a shorthand for a
> +'all'-member object. The C code generated for the definition will then be
> guarded
Please try to make your changes blend into the existing text: limit line
length to 70 characters, and put two spaces between sentences.
I doubt the CFG-ID non-terminal is useful. Elsewhere, we do without,
e.g. ENUM-VALUE, ALTERNATIVE, FEATURE.
Sure the [ COND, ... ] sugar is worth the bother?
Perhaps
COND = STRING
| { 'all: [ COND, ... ] }
| { 'any: [ COND, ... ] }
| { 'not': COND }
All definitions take an optional 'if' member. The form STRING is
shorthand for { 'any': [ STRING ] }. The C code generated ...
> +by an #if precessor expression generated from that condition: 'all': [COND,
> ...]
> +will generate '(COND && ...)', 'any': [COND, ...] '(COND || ...)', 'not':
> COND '!COND'.
The technical term is "#if preprocessing directive". Let's use it.
I find the last part unnecessarily hard to read. What about:
... generated from that condition:
* { 'all': [COND, ...] } will generate #if (COND && ...)
* { 'any': [COND, ...] } will generate #if (COND || ...)
* { 'not': COND } will generate #if !COND
>
> Example: a conditional struct
>
> { 'struct': 'IfStruct', 'data': { 'foo': 'int' },
> - 'if': ['CONFIG_FOO', 'HAVE_BAR'] }
> + 'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
>
> gets its generated code guarded like this:
>
> - #if defined(CONFIG_FOO)
> - #if defined(HAVE_BAR)
> + #if defined(CONFIG_FOO) && defined(HAVE_BAR)
> ... generated code ...
> - #endif /* defined(HAVE_BAR) */
> - #endif /* defined(CONFIG_FOO) */
> + #endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
>
> Individual members of complex types, commands arguments, and
> event-specific data can also be made conditional. This requires the
