Eric Blake <ebl...@redhat.com> 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 <marcandre.lur...@redhat.com> > Signed-off-by: Eric Blake <ebl...@redhat.com> > Signed-off-by: Markus Armbruster <arm...@redhat.com> > > --- > 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.