Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-11-02' into staging

QAPI patches

# gpg: Signature made Mon 02 Nov 2015 09:07:23 GMT using RSA key ID EB918653
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>"
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>"

* remotes/armbru/tags/pull-qapi-2015-11-02: (25 commits)
  qapi: Simplify gen_struct_field()
  qapi: Reserve 'u' member name
  qapi: Finish converting to new qapi union layout
  tpm: Convert to new qapi union layout
  memory: Convert to new qapi union layout
  input: Convert to new qapi union layout
  char: Convert to new qapi union layout
  net: Convert to new qapi union layout
  sockets: Convert to new qapi union layout
  block: Convert to new qapi union layout
  tests: Convert to new qapi union layout
  qapi-visit: Convert to new qapi union layout
  qapi: Start converting to new qapi union layout
  qapi-visit: Remove redundant functions for flat union base
  qapi: Unbox base members
  qapi: Prefer typesafe upcasts to qapi base classes
  qapi-types: Refactor base fields output
  qapi-visit: Split off visit_type_FOO_fields forward decl
  vnc: Hoist allocation of VncBasicInfo to callers
  qapi: Reserve 'q_*' and 'has_*' member names
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 9 insertions, 5 deletions

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 2afab20f55..4d8c2fcf02 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -106,12 +106,15 @@ Types, commands, and events share a common namespace.  Therefore,
 generally speaking, type definitions should always use CamelCase for
 user-defined type names, while built-in types are lowercase. Type
 definitions should not end in 'Kind', as this namespace is used for
-creating implicit C enums for visiting union types.  Command names,
+creating implicit C enums for visiting union types, or in 'List', as
+this namespace is used for creating array types.  Command names,
 and field names within a type, should be all lower case with words
 separated by a hyphen.  However, some existing older commands and
 complex types use underscore; when extending such expressions,
 consistency is preferred over blindly avoiding underscore.  Event
-names should be ALL_CAPS with words separated by underscore.
+names should be ALL_CAPS with words separated by underscore.  Field
+names cannot start with 'has-' or 'has_', as this is reserved for
+tracking optional fields.
 
 Any name (command, event, type, field, or enum value) beginning with
 "x-" is marked experimental, and may be withdrawn or changed
@@ -122,9 +125,10 @@ vendor), even if the rest of the name uses dash (example:
 __com.redhat_drive-mirror).  Other than downstream extensions (with
 leading underscore and the use of dots), all names should begin with a
 letter, and contain only ASCII letters, digits, dash, and underscore.
-It is okay to reuse names that match C keywords; the generator will
-rename a field named "default" in the QAPI to "q_default" in the
-generated C code.
+Names beginning with 'q_' are reserved for the generator: QMP names
+that resemble C keywords or other problematic strings will be munged
+in C to use this prefix.  For example, a field named "default" in
+qapi becomes "q_default" in the generated C code.
 
 In the rest of this document, usage lines are given for each
 expression type, with literal strings written in lower case and