Re: [Qemu-devel] [PATCH v9 37/37] qapi: Update docs to match recent generator changes

[Markus Armbruster]

Eric Blake <address@hidden> writes:

> Several commits have been changing the generator, but not updating
> the docs to match:
> - The implicit tag member is named "type", not "kind".  Screwed up in
> commit 39a1815.
> - Commit 9f08c8ec made list types lazy, and thereby dropped
> UserDefOneList if nothing explicitly uses the list type.
> - The parameter order has switched 'name' to occur earlier.
> - The generated code now checks for partial allocations.
> - etc.
>
> Rework the examples to show slightly more output (we don't want to
> show too much; that's what the testsuite is for), and regenerate the
> output to match all recent changes.
>
> Reported-by: Marc-André Lureau <address@hidden>
> Signed-off-by: Eric Blake <address@hidden>
> Signed-off-by: Markus Armbruster <address@hidden>
>
> ---
> v9: new patch
> ---
>  docs/qapi-code-gen.txt | 130 
> +++++++++++++++++++++++++++++--------------------
>  1 file changed, 78 insertions(+), 52 deletions(-)
>
> diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
> index 128f074..ae7b1a5 100644
> --- a/docs/qapi-code-gen.txt
> +++ b/docs/qapi-code-gen.txt
> @@ -1,7 +1,7 @@
>  = How to use the QAPI code generator =
>
>  Copyright IBM Corp. 2011
> -Copyright (C) 2012-2015 Red Hat, Inc.
> +Copyright (C) 2012-2016 Red Hat, Inc.
>
>  This work is licensed under the terms of the GNU GPL, version 2 or
>  later. See the COPYING file in the top-level directory.
> @@ -655,7 +655,7 @@ Union types
>
>      { "name": "BlockdevOptions", "meta-type": "object",
>        "members": [
> -          { "name": "kind", "type": "BlockdevOptionsKind" } ],
> +          { "name": "type", "type": "BlockdevOptionsKind" } ],
>        "tag": "type",
>        "variants": [
>            { "case": "file", "type": ":obj-FileOptions-wrapper" },
> @@ -721,29 +721,34 @@ the names of built-in types.  Clients should examine 
> member
>
>  == Code generation ==
>
> -Schemas are fed into four scripts to generate all the code/files that,
> +Schemas are fed into five scripts to generate all the code/files that,
>  paired with the core QAPI libraries, comprise everything required to
>  take JSON commands read in by a Client JSON Protocol server, unmarshal
>  the arguments into the underlying C types, call into the corresponding
> -C function, and map the response back to a Client JSON Protocol
> -response to be returned to the user.
> +C function, map the response back to a Client JSON Protocol response
> +to be returned to the user, and introspect the commands.
>
> -As an example, we'll use the following schema, which describes a single
> -complex user-defined type (which will produce a C struct, along with a list
> -node structure that can be used to chain together a list of such types in
> -case we want to accept/return a list of this type with a command), and a
> -command which takes that type as a parameter and returns the same type:
> +As an example, we'll use the following schema, which describes a
> +single complex user-defined type, along with command which takes a
> +list of that type as a parameter.

Lost: and returns the same type

>                                     The user is responsible for writing
> +the implementation of qmp_my_command(); everything else is produced by
> +the generator.
>
>      $ cat example-schema.json
>      { 'struct': 'UserDefOne',
> -      'data': { 'integer': 'int', 'string': 'str' } }
> +      'data': { 'integer': 'int', '*string': 'str' } }
>
>      { 'command': 'my-command',
> -      'data':    {'arg1': 'UserDefOne'},
> +      'data':    { 'arg1': ['UserDefOne'] },
>        'returns': 'UserDefOne' }
>
>      { 'event': 'MY_EVENT' }
>
> +For a more thorough look at generated code, the testsuite includes
> +tests/qapi-schema/qapi-schema-tests.json that covers more examples of
> +what the generator will accept, and compiles the resulting C code as
> +part of 'make check-unit'.
> +

Good idea.

Remaining changes are all to example output.  I'll check them when we're
closer to merging this series.