qapi: Tweak doc references to QMP when QGA is also meant

We have more than one qapi schema in use by more than one protocol.
Add a new term 'Client JSON Protocol' for use throughout the
document, to avoid confusion on whether something refers only to
QMP and not QGA.

Signed-off-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

docs/qapi-code-gen.txt

@@ -13,12 +13,14 @@ functionality to internal and external users. For external
 users/processes, this interface is made available by a JSON-based wire
 format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
 well as the QEMU Guest Agent (QGA) for communicating with the guest.
+The remainder of this document uses "Client JSON Protocol" when
+referring to the wire contents of a QMP or QGA connection.
 
-To map QMP and QGA interfaces to the native C QAPI implementations, a
+To map Client JSON Protocol interfaces to the native C QAPI
-JSON-based schema is used to define types and function signatures, and
+implementations, a JSON-based schema is used to define types and
-a set of scripts is used to generate types, signatures, and
+function signatures, and a set of scripts is used to generate types,
-marshaling/dispatch code. This document will describe how the schemas,
+signatures, and marshaling/dispatch code. This document will describe
-scripts, and resulting code are used.
+how the schemas, scripts, and resulting code are used.
 
 
 == QMP/Guest agent schema ==
@@ -34,13 +36,13 @@ generated C structs and parameter lists).  Ordering doesn't matter
 between top-level expressions or the keys within an expression, but
 does matter within dictionary values for 'data' and 'returns' members
 of a single expression.  QAPI schema input is written using 'single
-quotes' instead of JSON's "double quotes" (in contrast, QMP uses no
+quotes' instead of JSON's "double quotes" (in contrast, Client JSON
-comments, and while input accepts 'single quotes' as an extension,
+Protocol uses no comments, and while input accepts 'single quotes' as
-output is strict JSON using only "double quotes").  As in JSON,
+an extension, output is strict JSON using only "double quotes").  As
-trailing commas are not permitted in arrays or dictionaries.  Input
+in JSON, trailing commas are not permitted in arrays or dictionaries.
-must be ASCII (although QMP supports full Unicode strings, the QAPI
+Input must be ASCII (although QMP supports full Unicode strings, the
-parser does not).  At present, there is no place where a QAPI schema
+QAPI parser does not).  At present, there is no place where a QAPI
-requires the use of JSON numbers or null.
+schema requires the use of JSON numbers or null.
 
 Comments are allowed; anything between an unquoted # and the following
 newline is ignored.  Although there is not yet a documentation
@@ -82,8 +84,11 @@ that will use those types.  Forward references are allowed: the parser
 scans in two passes, where the first pass learns all type names, and
 the second validates the schema and generates the code.  This allows
 the definition of complex structs that can have mutually recursive
-types, and allows for indefinite nesting of QMP that satisfies the
+types, and allows for indefinite nesting of Client JSON Protocol that
-schema.  A type name should not be defined more than once.
+satisfies the schema.  A type name should not be defined more than
+once.  It is permissible for the schema to contain additional types
+not used by any commands or events in the Client JSON Protocol, for
+the side effect of generated C code used internally.
 
 There are seven top-level expressions recognized by the parser:
 'include', 'command', 'struct', 'enum', 'union', 'alternate', and
@@ -182,7 +187,7 @@ struct is:
    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
 
 The use of '*' as a prefix to the name means the member is optional in
-the corresponding QMP usage.
+the corresponding JSON protocol usage.
 
 The default initialization value of an optional argument should not be changed
 between versions of QEMU unless the new default maintains backward
@@ -213,8 +218,8 @@ of use.
 
 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 struct's dictionary in the QMP wire format. An example
+of the new struct's dictionary in the Client JSON Protocol wire
-definition is:
+format. An example definition is:
 
  { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
  { 'struct': 'BlockdevOptionsGenericCOWFormat',
@@ -242,19 +247,19 @@ useful.  The list of strings should be lower case; if an enum name
 represents multiple words, use '-' between words.  The string 'max' is
 not allowed as an enum value, and values should not be repeated.
 
-The enumeration values are passed as strings over the QMP protocol,
+The enumeration values are passed as strings over the Client JSON
-but are encoded as C enum integral values in generated code.  While
+Protocol, but are encoded as C enum integral values in generated code.
-the C code starts numbering at 0, it is better to use explicit
+While the C code starts numbering at 0, it is better to use explicit
 comparisons to enum values than implicit comparisons to 0; the C code
 will also include a generated enum member ending in _MAX for tracking
 the size of the enum, useful when using common functions for
 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;
+enumeration members in any location without breaking clients of Client
-however, removing enum values would break compatibility.  For any
+JSON Protocol; however, removing enum values would break
-struct that has a field that will only contain a finite set of
+compatibility.  For any struct that has a field that will only contain
-string values, using an enum type for that field is better than
+a finite set of string values, using an enum type for that field is
-open-coding the field to be type 'str'.
+better than open-coding the field to be type 'str'.
 
 
 === Union types ===
@@ -280,10 +285,10 @@ values to data types like in this example:
    'data': { 'file': 'FileOptions',
              'qcow2': 'Qcow2Options' } }
 
-In the QMP wire format, a simple union is represented by a dictionary
+In the Client JSON Protocol, a simple union is represented by a
-that contains the 'type' field as a discriminator, and a 'data' field
+dictionary that contains the 'type' field as a discriminator, and a
-that is of the specified data type corresponding to the discriminator
+'data' field that is of the specified data type corresponding to the
-value, as in these examples:
+discriminator value, as in these examples:
 
  { "type": "file", "data" : { "filename": "/some/place/my-image" } }
  { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
@@ -366,16 +371,16 @@ Just like for a simple union, an implicit C enum 'NameKind' is created
 to enumerate the branches for the alternate 'Name'.
 
 Unlike a union, the discriminator string is never passed on the wire
-for QMP.  Instead, the value's JSON type serves as an implicit
+for the Client JSON Protocol.  Instead, the value's JSON type serves
-discriminator, which in turn means that an alternate can only express
+as an implicit discriminator, which in turn means that an alternate
-a choice between types represented differently in JSON.  If a branch
+can only express a choice between types represented differently in
-is typed as the 'bool' built-in, the alternate accepts true and false;
+JSON.  If a branch is typed as the 'bool' built-in, the alternate
-if it is typed as any of the various numeric built-ins, it accepts a
+accepts true and false; if it is typed as any of the various numeric
-JSON number; if it is typed as a 'str' built-in or named enum type, it
+built-ins, it accepts a JSON number; if it is typed as a 'str'
-accepts a JSON string; and if it is typed as a complex type (struct or
+built-in or named enum type, it accepts a JSON string; and if it is
-union), it accepts a JSON object.  Two different complex types, for
+typed as a complex type (struct or union), it accepts a JSON object.
-instance, aren't permitted, because both are represented as a JSON
+Two different complex types, for instance, aren't permitted, because
-object.
+both are represented as a JSON object.
 
 The example alternate declaration above allows using both of the
 following example objects:
@@ -394,37 +399,37 @@ Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
 
 Commands are defined by using a dictionary containing several members,
 where three members are most common.  The 'command' member is a
-mandatory string, and determines the "execute" value passed in a QMP
+mandatory string, and determines the "execute" value passed in a
-command exchange.
+Client JSON Protocol command exchange.
 
 The 'data' argument maps to the "arguments" dictionary passed in as
-part of a QMP command.  The 'data' member is optional and defaults to
+part of a Client JSON Protocol command.  The 'data' member is optional
-{} (an empty dictionary).  If present, it must be the string name of a
+and defaults to {} (an empty dictionary).  If present, it must be the
-complex type, a one-element array containing the name of a complex
+string name of a complex type, a one-element array containing the name
-type, or a dictionary that declares an anonymous type with the same
+of a complex type, or a dictionary that declares an anonymous type
-semantics as a 'struct' expression, with one exception noted below when
+with the same semantics as a 'struct' expression, with one exception
-'gen' is used.
+noted below when '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
+of a Client JSON Protocol reply on successful completion of a command.
-optional from the command declaration; if absent, the "return" field
+The member is optional from the command declaration; if absent, the
-will be an empty dictionary.  If 'returns' is present, it must be the
+"return" field will be an empty dictionary.  If 'returns' is present,
-string name of a complex or built-in type, a one-element array
+it must be the string name of a complex or built-in type, a
-containing the name of a complex or built-in type, or a dictionary
+one-element array containing the name of a complex or built-in type,
-that declares an anonymous type with the same semantics as a 'struct'
+or a dictionary that declares an anonymous type with the same
-expression, with one exception noted below when 'gen' is used.
+semantics as a 'struct' expression, with one exception noted below
-Although it is permitted to have the 'returns' member name a built-in
+when 'gen' is used.  Although it is permitted to have the 'returns'
-type or an array of built-in types, any command that does this cannot
+member name a built-in type or an array of built-in types, any command
-be extended to return additional information in the future; thus, new
+that does this cannot be extended to return additional information in
-commands should strongly consider returning a dictionary-based type or
+the future; thus, new commands should strongly consider returning a
-an array of dictionaries, even if the dictionary only contains one
+dictionary-based type or an array of dictionaries, even if the
-field at the present.
+dictionary only contains one field at the present.
 
-All commands use a dictionary to report failure, with no way to
+All commands in Client JSON Protocol use a dictionary to report
-specify that in QAPI.  Where the error return is different than the
+failure, with no way to specify that in QAPI.  Where the error return
-usual GenericError class in order to help the client react differently
+is different than the usual GenericError class in order to help the
-to certain error conditions, it is worth documenting this in the
+client react differently to certain error conditions, it is worth
-comments before the command declaration.
+documenting this in the comments before the command declaration.
 
 Some example commands:
 
@@ -434,7 +439,7 @@ Some example commands:
  { 'command': 'my-second-command',
    'returns': [ 'MyType' ] }
 
-which would validate this QMP transaction:
+which would validate this Client JSON Protocol transaction:
 
  => { "execute": "my-first-command",
       "arguments": { "arg1": "hello" } }
@@ -443,14 +448,14 @@ which would validate this QMP transaction:
  <= { "return": [ { "value": "one" }, { } ] }
 
 In rare cases, QAPI cannot express a type-safe representation of a
-corresponding QMP command.  In these cases, if the command expression
+corresponding Client JSON Protocol command.  In these cases, if the
-includes the key 'gen' with boolean value false, then the 'data' or
+command expression includes the key 'gen' with boolean value false,
-'returns' member that intends to bypass generated type-safety and do
+then the 'data' or 'returns' member that intends to bypass generated
-its own manual validation should use an inline dictionary definition,
+type-safety and do its own manual validation should use an inline
-with a value of '**' rather than a valid type name for the keys that
+dictionary definition, with a value of '**' rather than a valid type
-the generated code will not validate.  Please try to avoid adding new
+name for the keys that the generated code will not validate.  Please
-commands that rely on this, and instead use type-safe unions.  For an
+try to avoid adding new commands that rely on this, and instead use
-example of bypass usage:
+type-safe unions.  For an example of bypass usage:
 
  { 'command': 'netdev_add',
    'data': {'type': 'str', 'id': 'str', '*props': '**'},
@@ -494,9 +499,9 @@ Resulting in this JSON object:
 
 Schemas are fed into 3 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 QMP/guest agent server, unmarshal the arguments into
+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 QMP/guest agent response to be returned to the user.
+response back to a Client JSON Protocol response to be returned to the user.
 
 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