==== Expression documentation ====
-Each expression that isn't an include directive must be preceded by a
+Each expression that isn't an include directive may be preceded by a
documentation block. Such blocks are called expression documentation
blocks.
+When documentation is required (see pragma 'doc-required'), expression
+documentation blocks are mandatory.
+
The documentation block consists of a first line naming the
expression, an optional overview, a description of each argument (for
commands and events) or member (for structs, unions and alternates),
not used by any commands or events in the Client JSON Protocol, for
the side effect of generated C code used internally.
-There are seven top-level expressions recognized by the parser:
-'include', 'command', 'struct', 'enum', 'union', 'alternate', and
-'event'. There are several groups of types: simple types (a number of
-built-in types, such as 'int' and 'str'; as well as enumerations),
-complex types (structs and two flavors of unions), and alternate types
-(a choice between other types). The 'command' and 'event' expressions
-can refer to existing types by name, or list an anonymous type as a
-dictionary. Listing a type name inside an array refers to a
-single-dimension array of that type; multi-dimension arrays are not
-directly supported (although an array of a complex struct that
-contains an array member is possible).
+There are eight top-level expressions recognized by the parser:
+'include', 'pragma', 'command', 'struct', 'enum', 'union',
+'alternate', and 'event'. There are several groups of types: simple
+types (a number of built-in types, such as 'int' and 'str'; as well as
+enumerations), complex types (structs and two flavors of unions), and
+alternate types (a choice between other types). The 'command' and
+'event' expressions can refer to existing types by name, or list an
+anonymous type as a dictionary. Listing a type name inside an array
+refers to a single-dimension array of that type; multi-dimension
+arrays are not directly supported (although an array of a complex
+struct that contains an array member is possible).
All names must begin with a letter, and contain only ASCII letters,
digits, hyphen, and underscore. There are two exceptions: enum values
QType QType JSON string matching enum QType values
-=== Includes ===
+=== Include directives ===
Usage: { 'include': STRING }
prevent incomplete include files.
+=== Pragma directives ===
+
+Usage: { 'pragma': DICT }
+
+The pragma directive lets you control optional generator behavior.
+The dictionary's entries are pragma names and values.
+
+Pragma's scope is currently the complete schema. Setting the same
+pragma to different values in parts of the schema doesn't work.
+
+Pragma 'doc-required' takes a boolean value. If true, documentation
+is required. Default is false.
+
+
=== Struct types ===
Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME }
'QType': 'QTYPE_QSTRING',
}
+# Are documentation comments required?
+doc_required = False
+
# Whitelist of commands allowed to return a non-dictionary
returns_whitelist = [
# From QMP:
"Value of 'include' must be a string")
self._include(include, info, os.path.dirname(abs_fname),
previously_included)
+ elif "pragma" in expr:
+ if len(expr) != 1:
+ raise QAPISemError(info, "Invalid 'pragma' directive")
+ pragma = expr['pragma']
+ if not isinstance(pragma, dict):
+ raise QAPISemError(
+ info, "Value of 'pragma' must be a dictionary")
+ for name, value in pragma.iteritems():
+ self._pragma(name, value, info)
else:
expr_elem = {'expr': expr,
'info': info}
self.exprs.extend(exprs_include.exprs)
self.docs.extend(exprs_include.docs)
+ def _pragma(self, name, value, info):
+ global doc_required
+ if name == 'doc-required':
+ if not isinstance(value, bool):
+ raise QAPISemError(info,
+ "Pragma 'doc-required' must be boolean")
+ doc_required = value
+ else:
+ raise QAPISemError(info, "Unknown pragma '%s'" % name)
+
def accept(self, skip_comment=True):
while True:
self.tok = self.src[self.cursor]
expr = expr_elem['expr']
info = expr_elem['info']
- if 'doc' not in expr_elem:
+ if 'doc' not in expr_elem and doc_required:
raise QAPISemError(info,
"Expression missing documentation comment")
qapi-schema += doc-invalid-return.json
qapi-schema += doc-invalid-section.json
qapi-schema += doc-invalid-start.json
+qapi-schema += doc-missing.json
qapi-schema += doc-missing-colon.json
qapi-schema += doc-missing-expr.json
qapi-schema += doc-missing-space.json
qapi-schema += ident-with-escape.json
qapi-schema += include-before-err.json
qapi-schema += include-cycle.json
+qapi-schema += include-extra-junk.json
qapi-schema += include-format-err.json
qapi-schema += include-nested-err.json
qapi-schema += include-no-file.json
qapi-schema += missing-type.json
qapi-schema += nested-struct-data.json
qapi-schema += non-objects.json
+qapi-schema += pragma-doc-required-crap.json
+qapi-schema += pragma-extra-junk.json
+qapi-schema += pragma-non-dict.json
qapi-schema += qapi-schema-test.json
qapi-schema += quoted-structural-chars.json
qapi-schema += redefined-builtin.json
projects / qemu.git / commitdiff