From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35756) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavR4-0005Cd-HR for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YavQx-0000VX-E0 for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:10 -0400 Received: from resqmta-po-01v.sys.comcast.net ([96.114.154.160]:55412) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YavQx-0000V8-8Q for qemu-devel@nongnu.org; Wed, 25 Mar 2015 20:14:03 -0400 From: Eric Blake Date: Wed, 25 Mar 2015 18:13:55 -0600 Message-Id: <1427328837-4406-4-git-send-email-eblake@redhat.com> In-Reply-To: <1427328837-4406-1-git-send-email-eblake@redhat.com> References: <1427328837-4406-1-git-send-email-eblake@redhat.com> Subject: [Qemu-devel] [PATCH 3/5] qapi: Make placeholders more obvious in doc usage statements List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: armbru@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 --- 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