[Qemu-devel] [PATCH 1/5] qapi: Minor tweaks to qapi-code-gen.txt

[Eric Blake <eblake@redhat.com>]

Several minor things pointed out by Markus during review of my
sweeping changes.

Signed-off-by: Eric Blake <eblake@redhat.com>
---
 docs/qapi-code-gen.txt | 44 ++++++++++++++++++++++++++------------------
 1 file changed, 26 insertions(+), 18 deletions(-)

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 8792b94..1f7d0ca 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -82,13 +82,14 @@ 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
 'event'.  There are several built-in types, such as 'int' and 'str';
-additionally, the top-level expressions can define complex types,
-enumeration types, two flavors of union types, and an alternate type.
-The 'command' expression can refer to existing types by name, or list
-an anonymous type as a dictionary.  Listing a type name inside an
-array refers to a single-dimension array of that type; multi-dimension
-arrays are not directly supported (although an array of a complex
-struct that contains an array member is possible).
+additionally, the top-level expressions can define complex types
+(structs and two flavors of unions), as well as enumeration and
+alternate types.  The 'command' and 'event' expressions can refer to
+existing types by name, or list an anonymous type as a dictionary.
+Listing a type name inside an array refers to a single-dimension array
+of that type; multi-dimension arrays are not directly supported
+(although an array of a complex struct that contains an array member
+is possible).

 Types, commands, and events share a common namespace.  Therefore,
 generally speaking, type definitions should always use CamelCase for
@@ -117,6 +118,12 @@ underscore.  It is okay to reuse names that match C keywords; the
 generator will rename a field named "default" in the QAPI to
 "q_default" in the generated C code.

+In the rest of this document, usage lines are given for each
+expression type, written in the style of the QAPI syntax.  For
+example, a usage statement that includes '*base':'complex-type-name'
+means that an expression has an optional key 'base', which if present
+must have a value that forms a 'complex-type-name'.
+

 === Built-in Types ===

@@ -138,7 +145,7 @@ Usage: { 'include': 'str' }

 The QAPI schema definitions can be modularized using the 'include' directive:

- { 'include': 'path/to/file.json'}
+ { 'include': 'path/to/file.json' }

 The directive is evaluated recursively, and include paths are relative to the
 file using the directive. Multiple includes of the same file are
@@ -159,8 +166,8 @@ Usage: { 'type': 'str', 'data': 'dict', '*base': 'complex-type-name' }
 A complex type 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
-complex, enum, union, alternate, or built-in type, or a one-element
-array containing a type name.  An example of a complex type is:
+type, or a one-element array containing a type name.  An example of a
+complex type is:

  { 'type': 'MyType',
    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
@@ -280,8 +287,9 @@ implicit enum.
 A flat union definition specifies a complex type as its base, and
 avoids nesting on the wire.  In this case, the fields of the complex
 type are included as top-level fields of the union dictionary in the
-QMP wire format, and the 'discriminator' field must be the name of an
-enum-typed member of the base type. An example definition is:
+QMP wire format common to all branches of the union, and the
+'discriminator' field must be the name of an enum-typed member of the
+base type. An example definition is:

  { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
  { 'union': 'BlockdevOptions',
@@ -350,7 +358,7 @@ This example allows using both of the following example objects:
 === Commands ===

 Usage: { 'command': 'str', '*data': 'dict-or-complex-type-name',
-         '*returns': 'type',
+         '*returns': 'dict-or-type-name',
          '*gen': false, '*success-response': false }

 Commands are defined by using a dictionary containing several members,
@@ -358,13 +366,13 @@ where three members are most common.  The 'command' member is a
 mandatory string, and determines the "execute" value passed in a QMP
 command exchange.

-The 'data' member is optional; if absent, the command accepts an
-optional empty dictionary.  If present, it must be the string name of
-a complex type, a one-element array containing the name of a complex
+The 'data' argument maps to the "arguments" dictionary passed in as
+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
-'gen' is used.  The 'data' argument maps to the "arguments" dictionary
-passed in as part of a QMP command.
+'gen' is used.

 The 'returns' member describes what will appear in the "return" field
 of a QMP reply on successful completion of a command.  The member is
-- 
2.1.0