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 <arm...@redhat.com> Message-ID: <20250228134335.132278-1-arm...@redhat.com> Reviewed-by: Daniel P. Berrangé <berra...@redhat.com> --- docs/devel/qapi-code-gen.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 9fa94251b0..f9cfe8721f 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 -- 2.48.1
