Eric Blake <ebl...@redhat.com> writes: > Referring to "type" as both a meta-type (built-in, enum, union, > alternte, or struct) and a specific type (the name that the > schema uses for declaring structs) is confusing. Now that the > generator accepts 'struct' as a synonym for 'type', update all > documentation to use saner wording. > > Signed-off-by: Eric Blake <ebl...@redhat.com> > > --- > > v6: new patch > --- > docs/qapi-code-gen.txt | 56 > +++++++++++++++++++++++++------------------------- > 1 file changed, 28 insertions(+), 28 deletions(-) > > diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt > index 8a76cc1..6206032 100644 > --- a/docs/qapi-code-gen.txt > +++ b/docs/qapi-code-gen.txt > @@ -71,7 +71,7 @@ x.y.z)' comment. For example: > # > # Since: 0.14.0 > ## > - { 'type': 'BlockStats', > + { 'struct': 'BlockStats', > 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', > '*parent': 'BlockStats', > '*backing': 'BlockStats'} } > @@ -85,7 +85,7 @@ types, and allows for indefinite nesting of QMP that > satisfies the > schema. A type name should not be defined more than once. > > There are seven top-level expressions recognized by the parser: > -'include', 'command', 'type', 'enum', 'union', 'alternate', and > +'include', 'command', 'struct', 'enum', 'union', 'alternate', and > 'event'. There are several groups of types: simple types (a number of > built-in types, such as 'int' and 'str'; as well as enumerations), > complex types (structs and two flavors of unions), and alternate types > @@ -127,9 +127,9 @@ In the rest of this document, usage lines are given for > each > expression type, with literal strings written in lower case and > placeholders written in capitals. If a literal string includes a > prefix of '*', that key/value pair can be omitted from the expression. > -For example, a usage statement that includes '*base':COMPLEX-TYPE-NAME > +For example, a usage statement that includes '*base':STRUCT-NAME > means that an expression has an optional key 'base', which if present > -must have a value that forms a complex type name. > +must have a value that forms a struct name. > > > === Built-in Types === > @@ -167,17 +167,17 @@ an outer file. The parser may be made stricter in the > future to > prevent incomplete include files. > > > -=== Complex types === > +=== Struct types === > > -Usage: { 'type': STRING, 'data': DICT, '*base': COMPLEX-TYPE-NAME } > +Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } > > -A complex type is a dictionary containing a single 'data' key whose > +A struct is a dictionary containing a single 'data' key whose > value is a dictionary. This corresponds to a struct in C or an Object > in JSON. Each value of the 'data' dictionary must be the name of a > type, or a one-element array containing a type name. An example of a > -complex type is: > +struct is: > > - { 'type': 'MyType', > + { 'struct': 'MyType', > 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } > > The use of '*' as a prefix to the name means the member is optional in > @@ -210,13 +210,13 @@ A structure that is used in both input and output of > various commands > must consider the backwards compatibility constraints of both directions > of use. > > -A complex type definition can specify another complex type as its base. > +A struct definition can specify another struct as its base. > In this case, the fields of the base type are included as top-level fields > -of the new complex type's dictionary in the QMP wire format. An example > +of the new struct's dictionary in the QMP wire format. An example > definition is: > > - { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } > - { 'type': 'BlockdevOptionsGenericCOWFormat', > + { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } > + { 'struct': 'BlockdevOptionsGenericCOWFormat', > 'base': 'BlockdevOptionsGenericFormat', > 'data': { '*backing': 'str' } } > > @@ -251,7 +251,7 @@ converting between strings and enum values. Since the > wire format > always passes by name, it is acceptable to reorder or add new > enumeration members in any location without breaking QMP clients; > however, removing enum values would break compatibility. For any > -complex type that has a field that will only contain a finite set of > +struct that has a field that will only contain a finite set of > string values, using an enum type for that field is better than > open-coding the field to be type 'str'. > > @@ -259,7 +259,7 @@ open-coding the field to be type 'str'. > === Union types === > > Usage: { 'union': STRING, 'data': DICT } > -or: { 'union': STRING, 'data': DICT, 'base': COMPLEX-TYPE-NAME, > +or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME, > 'discriminator': ENUM-MEMBER-OF-BASE } > > Union types are used to let the user choose between several different > @@ -271,8 +271,8 @@ paragraphs. > A simple union type defines a mapping from automatic discriminator > values to data types like in this example: > > - { 'type': 'FileOptions', 'data': { 'filename': 'str' } } > - { 'type': 'Qcow2Options', > + { 'struct': 'FileOptions', 'data': { 'filename': 'str' } } > + { 'struct': 'Qcow2Options', > 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } > > { 'union': 'BlockdevOptions', > @@ -295,13 +295,13 @@ the union can be named 'max', as this would collide > with the implicit > enum. The value for each branch can be of any type. > > > -A flat union definition specifies a complex type as its base, and > +A flat union definition specifies a struct as its base, and > avoids nesting on the wire. All branches of the union must be > complex types, and the top-level fields of the union dictionary on > the wire will be combination of fields from both the base type and the > appropriate branch type (when merging two dictionaries, there must be > no keys in common). The 'discriminator' field must be the name of an > -enum-typed member of the base type. > +enum-typed member of the base struct. > > The following example enhances the above simple union example by > adding a common field 'readonly', renaming the discriminator to > @@ -309,7 +309,7 @@ something more applicable, and reducing the number of {} > required on > the wire: > > { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] } > - { 'type': 'BlockdevCommonOptions', > + { 'struct': 'BlockdevCommonOptions', > 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } > { 'union': 'BlockdevOptions', > 'base': 'BlockdevCommonOptions', > @@ -341,9 +341,9 @@ union has a complex type with a single member named > 'data'. That is, A simple union can always be re-written as a flat union where the base class has a single member named 'type', and where each branch of the union has a complex type with a single member named 'data'. That is,
Should we use 'struct' instead of 'complex type' here? { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } > is identical on the wire to: > > { 'enum': 'Enum', 'data': ['one', 'two'] } > - { 'type': 'Base', 'data': { 'type': 'Enum' } } > - { 'type': 'Branch1', 'data': { 'data': 'str' } } > - { 'type': 'Branch2', 'data': { 'data': 'int' } } > + { 'struct': 'Base', 'data': { 'type': 'Enum' } } > + { 'struct': 'Branch1', 'data': { 'data': 'str' } } > + { 'struct': 'Branch2', 'data': { 'data': 'int' } } > { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type', > 'data': { 'one': 'Branch1', 'two': 'Branch2' } } > > @@ -401,7 +401,7 @@ part of a QMP command. The 'data' member is optional and > defaults to > {} (an empty dictionary). If present, it must be the string name of a > complex type, a one-element array containing the name of a complex > type, or a dictionary that declares an anonymous type with the same > -semantics as a 'type' expression, with one exception noted below when > +semantics as a 'struct' expression, with one exception noted below when > 'gen' is used. > > The 'returns' member describes what will appear in the "return" field > @@ -410,7 +410,7 @@ optional from the command declaration; if absent, the > "return" field > will be an empty dictionary. If 'returns' is present, it must be the > string name of a complex or built-in type, a one-element array > containing the name of a complex or built-in type, or a dictionary > -that declares an anonymous type with the same semantics as a 'type' > +that declares an anonymous type with the same semantics as a 'struct' > expression, with one exception noted below when 'gen' is used. > Although it is permitted to have the 'returns' member name a built-in > type or an array of built-in types, any command that does this cannot > @@ -429,7 +429,7 @@ Some example commands: > > { 'command': 'my-first-command', > 'data': { 'arg1': 'str', '*arg2': 'str' } } > - { 'type': 'MyType', 'data': { '*value': 'str' } } > + { 'struct': 'MyType', 'data': { '*value': 'str' } } > { 'command': 'my-second-command', > 'returns': [ 'MyType' ] } > > @@ -473,7 +473,7 @@ Events are defined with the keyword 'event'. It is not > allowed to > name an event 'MAX', since the generator also produces a C enumeration > of all event names with a generated _MAX value at the end. When > 'data' is also specified, additional info will be included in the > -event, with similar semantics to a 'type' expression. Finally there > +event, with similar semantics to a 'struct' expression. Finally there > will be C API generated in qapi-event.h; when called by QEMU code, a > message with timestamp will be emitted on the wire. > > @@ -504,7 +504,7 @@ 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: > > $ cat example-schema.json > - { 'type': 'UserDefOne', > + { 'struct': 'UserDefOne', > 'data': { 'integer': 'int', 'string': 'str' } } > > { 'command': 'my-command', Reviewed-by: Markus Armbruster <arm...@redhat.com>