[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usa
From: |
Eric Blake |
Subject: |
[Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usage statements |
Date: |
Wed, 25 Mar 2015 18:13:55 -0600 |
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 <address@hidden>
---
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
- [Qemu-devel] [PATCH 0/5] qapi doc cleanups, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 2/5] qapi: Clean up documentation of alternate mappings, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 5/5] qapi: Fix QMP spec references to JSON, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usage statements,
Eric Blake <=
- [Qemu-devel] [PATCH 1/5] qapi: Minor tweaks to qapi-code-gen.txt, Eric Blake, 2015/03/25
- [Qemu-devel] [PATCH 4/5] qapi: Tweak doc references to QMP when QGA is also meant, Eric Blake, 2015/03/25
- Re: [Qemu-devel] [PATCH 0/5] qapi doc cleanups, Markus Armbruster, 2015/03/27