aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2017-03-15 13:56:54 +0100
committerMarkus Armbruster <armbru@redhat.com>2017-03-16 07:13:02 +0100
commit1554a8fae984cad4704fb94a8cef3c9b42ef6185 (patch)
tree78d963a98ad801e050bfbd0c6943bd4e9fc30c0c /docs
parent700dc9f503c61cdd1180e9bf84a225105b22b227 (diff)
qapi: Have each QAPI schema declare its returns white-list
qapi.py has a hardcoded white-list of command names that may violate the rules on permitted return types. Add a new pragma directive 'returns-whitelist', and use it to replace the hard-coded white-list. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1489582656-31133-6-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
Diffstat (limited to 'docs')
-rw-r--r--docs/qapi-code-gen.txt13
1 files changed, 7 insertions, 6 deletions
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 5532b60d91..3d17005cf6 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -318,6 +318,9 @@ 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.
+Pragma 'returns-whitelist' takes a list of command names that may
+violate the rules on permitted return types. Default is none.
+
=== Struct types ===
@@ -566,12 +569,10 @@ The member is optional from the command declaration; if absent, the
"return" member will be an empty dictionary. If 'returns' is present,
it must be the string name of a complex or built-in type, a
one-element array containing the name of a complex or built-in type.
-Although it is permitted to have the 'returns' member name a built-in
-type or an array of built-in types, any command that does this cannot
-be extended to return additional information in the future; thus, new
-commands should strongly consider returning a dictionary-based type or
-an array of dictionaries, even if the dictionary only contains one
-member at the present.
+To return anything else, you have to list the command in pragma
+'returns-whitelist'. If you do this, the command cannot be extended
+to return additional information in the future. Use of
+'returns-whitelist' for new commands is strongly discouraged.
All commands in Client JSON Protocol use a dictionary to report
failure, with no way to specify that in QAPI. Where the error return