[PATCH v3 1/5] qapi: Enable enum member introspection to show more than name

[Markus Armbruster]

Markus Armbruster <armbru at redhat.com> writes:

> The next commit will add feature flags to enum members.  There's a
> problem, though: query-qmp-schema shows an enum type's members as an
> array of member names (SchemaInfoEnum member @values).  If it showed
> an array of objects with a name member, we could simply add more
> members to these objects.  Since it's just strings, we can't.
>
> I can see three ways to correct this design mistake:
>
> 1. Do it the way we should have done it, plus compatibility goo.
>
>    We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum.  Since
>    changing @values would be a compatibility break, add a new member
>    @members instead.
>
>    @values is now redundant.  In my testing, output of
>    qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB).
>
>    We can deprecate @values now and drop it later.  This will break
>    outmoded clients.  Well-behaved clients such as libvirt are
>    expected to break cleanly.
>
> 2. Like 1, but omit "boring" elements of @member, and empty @member.
>
>    @values does not become redundant.  @members augments it.  Somewhat
>    cumbersome, but output of query-qmp-schema grows only as we make
>    enum members non-boring.
>
>    There is nothing to deprecate here.
>
> 3. Versioned query-qmp-schema.
>
>    query-qmp-schema provides either @values or @members.  The QMP
>    client can select which version it wants.  There is no redundant
>    output.
>
>    We can deprecate old versions and eventually drop them.  This will
>    break outmoded clients.  Breaking cleanly is easier than for 1.
>
>    While 1 and 2 operate within the common rules for compatible
>    evolution apply (section "Compatibility considerations" in
>    docs/devel/qapi-code-gen.rst), 3 bypasses them.  Attractive when
>    operating within the rules is just too awkward.  Not the case here.
>
> This commit implements 1.  Libvirt developers prefer it.
>
> Signed-off-by: Markus Armbruster <armbru at redhat.com>
> Reviewed-by: Eric Blake <eblake at redhat.com>
> Tested-by: Peter Krempa <pkrempa at redhat.com>
> Acked-by: Peter Krempa <pkrempa at redhat.com>

I meant to deprecate @values, but forgot.  I should really do it right
away, because... 

> ---
>  docs/devel/qapi-code-gen.rst | 15 +++++++++++----
>  qapi/introspect.json         | 21 +++++++++++++++++++--
>  scripts/qapi/introspect.py   | 18 ++++++++++++++----
>  3 files changed, 44 insertions(+), 10 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index b2569de486..d267889d2c 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1231,14 +1231,21 @@ Example: the SchemaInfo for ['str'] ::
>        "element-type": "str" }
>  
>  The SchemaInfo for an enumeration type has meta-type "enum" and
> -variant member "values".  The values are listed in no particular
> -order; clients must search the entire enum when learning whether a
> -particular value is supported.
> +variant member "members".
> +
> +"members" is a JSON array describing the enumeration values.  Each
> +element is a JSON object with member "name" (the member's name).  The
> +"members" array is in no particular order; clients must search the
> +entire array when learning whether a particular value is supported.
>  
>  Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
>  
>      { "name": "MyEnum", "meta-type": "enum",
> -      "values": [ "value1", "value2", "value3" ] }
> +      "members": [
> +        { "name": "value1" },
> +        { "name": "value2" },
> +        { "name": "value3" }
> +      ] }
>  
>  The SchemaInfo for a built-in type has the same name as the type in
>  the QAPI schema (see section `Built-in Types`_), with one exception

... this doesn't document @values anymore, only @members.

Done in v5.

[...]