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 <[email protected]> --- 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
