[Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usage statements

[Eric Blake <eblake@redhat.com>]

Using QAPI syntax to describe QAPI syntax is a bit meta; using
different typographic conventions makes it a bit easier to see
which strings are literal vs. placeholders.

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

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 7fb0db7..c155f95 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -119,10 +119,12 @@ 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'.
+expression type, with literal strings written in lower case and
+placeholders written in capitals.  If a literal string includes a
+prefix of '*', it can be omitted from that expression.  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 ===
@@ -141,7 +143,7 @@ The following types are built-in to the parser:

 === Includes ===

-Usage: { 'include': 'str' }
+Usage: { 'include': STRING }

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

@@ -161,7 +163,7 @@ prevent incomplete include files.

 === Complex types ===

-Usage: { 'type': 'str', 'data': 'dict', '*base': 'complex-type-name' }
+Usage: { 'type': STRING, '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
@@ -221,7 +223,7 @@ both fields like this:

 === Enumeration types ===

-Usage: { 'enum': 'str', 'data': [ 'str' ] }
+Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING }

 An enumeration type is a dictionary containing a single 'data' key
 whose value is a list of strings.  An example enumeration is:
@@ -250,9 +252,9 @@ open-coding the field to be type 'str'.

 === Union types ===

-Usage: { 'union': 'str', 'data': 'dict' }
-or:    { 'union': 'str', 'data': 'dict', 'base': 'complex-type-name',
-         'discriminator': 'enum-member-of-base' }
+Usage: { 'union': STRING, 'data': DICT }
+or:    { 'union': STRING, 'data': DICT, 'base': COMPLEX-TYPE-NAME,
+         'discriminator': ENUM-MEMBER-OF-BASE }

 Union types are used to let the user choose between several different
 data types.  There are two flavors: simple (no discriminator or base),
@@ -329,7 +331,7 @@ Resulting in this JSON object:

 === Alternate types ===

-Usage: { 'alternate: 'str', 'data': 'dict' }
+Usage: { 'alternate: STRING, 'data': DICT }

 An alternate type is one that allows a choice between two or more JSON
 data types on the wire.  The definition is similar to a simple union
@@ -361,8 +363,8 @@ This example allows using both of the following example objects:

 === Commands ===

-Usage: { 'command': 'str', '*data': 'dict-or-complex-type-name',
-         '*returns': 'dict-or-type-name',
+Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT,
+         '*returns': TYPE-NAME-OR-DICT,
          '*gen': false, '*success-response': false }

 Commands are defined by using a dictionary containing several members,
@@ -439,7 +441,7 @@ qemu-guest-agent makes use of this field.

 === Events ===

-Usage: { 'event': 'str', '*data': 'dict-or-complex-type-name' }
+Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT }

 Events are defined with the keyword 'event'.  It is not allowed to
 name an event 'MAX', since the generator also produces a C enumeration
-- 
2.1.0