[Qemu-devel] [RFC PATCH 18/32] docs/devel/qapi-code-gen.txt: Rewrite section on schema syntax

[Markus Armbruster]

Section "QMP/Guest agent schema" is one big paragraph, encumbered with
more detail than necessary.  It also claims JSON null isn't supported,
which is untrue since commit e53188a, v2.4.0.  Rewrite it.

Signed-off-by: Markus Armbruster <address@hidden>
---
 docs/devel/qapi-code-gen.txt | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index f5b7659caf..3186c36460 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -25,24 +25,24 @@ how the schemas, scripts, and resulting code are used.
 
 == QMP/Guest agent schema ==
 
-A QAPI schema file is designed to be loosely based on JSON
-(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
-and the use of comments; a QAPI schema file is then parsed by a python
-code generation program.  A valid QAPI schema consists of a series of
-top-level expressions, with no commas between them.  Where
-dictionaries (JSON objects) are used, they are parsed as python
-OrderedDicts so that ordering is preserved (for predictable layout of
-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, Client JSON
-Protocol uses no comments, and while input accepts 'single quotes' as
-an extension, output is strict JSON using only "double quotes").  As
-in JSON, trailing commas are not permitted in arrays or dictionaries.
-Input must be ASCII (although QMP supports full Unicode strings, the
-QAPI parser does not).  At present, there is no place where a QAPI
-schema requires the use of JSON numbers or null.
+Schema syntax is based on JSON (RFC 7159), with the following
+differences:
+
+* Comments (see below)
+
+* No JSON numbers
+
+* Strings use 'single quotes' instead of "double quotes"
+
+* The input character set is plain ASCII
+
+  Unicode characters need to be escaped.  In contrast, the Client JSON
+  Protocol uses UTF-8.
+
+A QAPI schema consists of a sequence of JSON values (top-level
+expressions), with no commas between them.  The order of top-level
+expressions doesn't matter.  The order of keys in JSON objects is
+generally relevant.
 
 
 === Comments ===
-- 
2.13.6