docs/devel/qapi-code-gen: Document 'features' introspection

Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to update section "Client JSON Protocol introspection", and commit
23394b4c39 "qapi: Add feature flags to commands" didn't either.  Make
up for that.

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

1 files changed, 28 insertions, 15 deletions

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 3ce03e6..300f277 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -642,13 +642,8 @@ that previously resulted in an error).  QMP clients may still need to
 know whether the extension is available.
 
 For this purpose, a list of features can be specified for a command or
-struct type.  This is exposed to the client as a list of strings,
-where each string signals that this build of QEMU shows a certain
-behaviour.
-
-Each member of the 'features' array defines a feature.  It can either
-be { 'name': STRING, '*if': COND }, or STRING, which is shorthand for
-{ 'name': STRING }.
+struct type.  Each list member can either be { 'name': STRING, '*if':
+COND }, or STRING, which is shorthand for { 'name': STRING }.
 
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
@@ -659,6 +654,12 @@ Example:
   'data': { 'number': 'int' },
   'features': [ 'allow-negative-numbers' ] }
 
+The feature strings are exposed to clients in introspection, as
+explained in section "Client JSON Protocol introspection".
+
+Intended use is to have each feature string signal that this build of
+QEMU shows a certain behaviour.
+
 
 === Naming rules and reserved names ===
 
@@ -965,7 +966,7 @@ schema, along with the SchemaInfo type.  This text attempts to give an
 overview how things work.  For details you need to consult the QAPI
 schema.
 
-SchemaInfo objects have common members "name" and "meta-type", and
+SchemaInfo objects have common members "name", "meta-type", and
 additional variant members depending on the value of meta-type.
 
 Each SchemaInfo object describes a wire ABI entity of a certain
@@ -985,12 +986,13 @@ references by name.
 QAPI schema definitions not reachable that way are omitted.
 
 The SchemaInfo for a command has meta-type "command", and variant
-members "arg-type", "ret-type" and "allow-oob".  On the wire, the
-"arguments" member of a client's "execute" command must conform to the
-object type named by "arg-type".  The "return" member that the server
-passes in a success response conforms to the type named by "ret-type".
-When "allow-oob" is true, it means the command supports out-of-band
-execution.  It defaults to false.
+members "arg-type", "ret-type", "allow-oob", and "features".  On the
+wire, the "arguments" member of a client's "execute" command must
+conform to the object type named by "arg-type".  The "return" member
+that the server passes in a success response conforms to the type
+named by "ret-type".  When "allow-oob" is true, it means the command
+supports out-of-band execution.  It defaults to false.  "features"
+exposes the command's feature strings as a JSON array of strings.
 
 If the command takes no arguments, "arg-type" names an object type
 without members.  Likewise, if the command returns nothing, "ret-type"
@@ -1025,7 +1027,8 @@ Example: the SchemaInfo for EVENT_C from section Events
 
 The SchemaInfo for struct and union types has meta-type "object".
 
-The SchemaInfo for a struct type has variant member "members".
+The SchemaInfo for a struct type has variant members "members" and
+"features".
 
 The SchemaInfo for a union type additionally has variant members "tag"
 and "variants".
@@ -1047,6 +1050,16 @@ Example: the SchemaInfo for MyType from section Struct types
           { "name": "member2", "type": "int" },
           { "name": "member3", "type": "str", "default": null } ] }
 
+"features" exposes the command's feature strings as a JSON array of
+strings.
+
+Example: the SchemaInfo for TestType from section Features:
+
+    { "name": "TestType", "meta-type": "object",
+      "members": [
+          { "name": "number", "type": "int" } ],
+      "features": ["allow-negative-numbers"] }
+
 "tag" is the name of the common member serving as type tag.
 "variants" is a JSON array describing the object's variant members.
 Each element is a JSON object with members "case" (the value of type