diff mbox series

[v4,9/9] docs: update the documentation about schema configuration

Message ID 20210517163040.2308926-10-marcandre.lureau@redhat.com (mailing list archive)
State New, archived
Headers show
Series qapi: untie 'if' conditions from C preprocessor | expand

Commit Message

Marc-André Lureau May 17, 2021, 4:30 p.m. UTC 
From: Marc-André Lureau <marcandre.lureau@redhat.com>

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Tested-by: John Snow <jsnow@redhat.com>
---
 docs/devel/qapi-code-gen.txt | 27 ++++++++++++++++-----------
 1 file changed, 16 insertions(+), 11 deletions(-)

Comments

Markus Armbruster May 21, 2021, 11:56 a.m. UTC | #1 
marcandre.lureau@redhat.com writes:

> From: Marc-André Lureau <marcandre.lureau@redhat.com>
>
> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
> Tested-by: John Snow <jsnow@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
Marc-André Lureau May 21, 2021, 12:29 p.m. UTC | #2 
Hi

On Fri, May 21, 2021 at 3:58 PM Markus Armbruster <armbru@redhat.com> wrote:

> marcandre.lureau@redhat.com writes:
>
> > From: Marc-André Lureau <marcandre.lureau@redhat.com>
> >
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
> > Tested-by: John Snow <jsnow@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.
>

ok


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

Maybe not


> 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 ...
>

ok


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

ok


> 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
>
>
Yes!

>
> >  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
>
>
>
thanks
diff mbox series

Patch

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
+by an #if precessor expression generated from that condition: 'all': [COND, ...]
+will generate '(COND && ...)', 'any': [COND, ...] '(COND || ...)', 'not': COND '!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