aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2025-02-28 14:43:35 +0100
committerMarkus Armbruster <armbru@redhat.com>2025-03-06 10:33:05 +0100
commit71ba2613ad470b6397868ae7333cd255e467be68 (patch)
tree54290f5f1d32471bd0dc141ce87ef73b53be2db2
parent45e5b49360224019eddd307e34ea5625e4e730bf (diff)
downloadqemu-71ba2613ad470b6397868ae7333cd255e467be68.zip
qemu-71ba2613ad470b6397868ae7333cd255e467be68.tar.gz
qemu-71ba2613ad470b6397868ae7333cd255e467be68.tar.bz2
docs/devel/qapi-code-gen: Discourage use of 'prefix'
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. Commit 7bbadc60b5..64f5e9db77 eliminated most uses. Discourage new ones. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250228134335.132278-1-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
-rw-r--r--docs/devel/qapi-code-gen.rst3
1 files changed, 2 insertions, 1 deletions
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 9fa9425..f9cfe87 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -229,7 +229,8 @@ These are of the form PREFIX_NAME, where PREFIX is derived from the
enumeration type's name, and NAME from the value's name. For the
example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The
-optional 'prefix' member overrides PREFIX.
+optional 'prefix' member overrides PREFIX. This is rarely necessary,
+and should be used with restraint.
The generated C enumeration constants have values 0, 1, ..., N-1 (in
QAPI schema order), where N is the number of values. There is an