Re: [Qemu-devel] [PATCH v6 23/27] qapi: add 'If:' condition to enum values documentation

[Markus Armbruster]

Marc-André Lureau <address@hidden> writes:

> Signed-off-by: Marc-André Lureau <address@hidden>
> ---
>  scripts/qapi/doc.py             | 5 ++++-
>  tests/qapi-schema/doc-good.json | 4 +++-
>  tests/qapi-schema/doc-good.out  | 1 +
>  tests/qapi-schema/doc-good.texi | 2 ++
>  4 files changed, 10 insertions(+), 2 deletions(-)
>
> diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
> index 76cb186ff9..196deea11d 100755
> --- a/scripts/qapi/doc.py
> +++ b/scripts/qapi/doc.py
> @@ -128,7 +128,10 @@ def texi_body(doc):
>  
>  def texi_enum_value(value):
>      """Format a table of members item for an enumeration value"""
> -    return '@item @code{%s}\n' % value.name
> +    return '@item @code{%s}%s\n' % (
> +        value.name,
> +        'address@hidden:} @code{%s}\n' %
> +        ', '.join(value.ifcond) if value.ifcond else '')
>  
>  

This code is a puzzle.  I don't like code puzzles.

>  def texi_member(member, suffix=''):
> diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
> index 984cd8ed06..c7fe08c530 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -55,7 +55,9 @@
>  #
>  # @two is undocumented
>  ##
> -{ 'enum': 'Enum', 'data': [ 'one', 'two' ], 'if': 'defined(IFCOND)' }
> +{ 'enum': 'Enum', 'data':
> +  [ { 'name': 'one', 'if': 'defined(IFENUM)' }, 'two' ],
> +  'if': 'defined(IFCOND)' }
>  
>  ##
>  # @Base:
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index c2fc5c774a..a05535b69b 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -11,6 +11,7 @@ enum QType
>  module doc-good.json
>  enum Enum
>      member one
> +        if ['defined(IFENUM)']
>      member two
>      if ['defined(IFCOND)']
>  object Base
> diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
> index e42eace474..2446a1c702 100644
> --- a/tests/qapi-schema/doc-good.texi
> +++ b/tests/qapi-schema/doc-good.texi
> @@ -83,6 +83,8 @@ Examples:
>  @b{Values:}
>  @table @asis
>  @item @code{one}
> address@hidden:} @code{defined(IFENUM)}
> +
>  The @emph{one} @{and address@hidden
>  @item @code{two}
>  Not documented

Odd: the @item is followed by a blank line only if its conditional.
Formatted to plain text, it looks like this:

 -- Enum: Enum

     Values:
     'one'
          If: 'defined(IFENUM)'

          The _one_ {and only}
     'two'
          Not documented
     'two' is undocumented

     If: 'defined(IFCOND)'

Odd^2: the "If:" line comes first for members, last for top-level
expressions like types.