From a05ec21958eb6afb6c7e419b8fb543e26c0d00e1 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Tue, 30 Jul 2024 22:01:27 +0200 Subject: [PATCH] attribute: Improve documentation. * lib/attribute.h: Clarify where to place the various attributes. --- ChangeLog | 5 +++++ lib/attribute.h | 49 +++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 48 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6bf78d04ff..872cc0f6cb 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2024-07-30 Bruno Haible + + attribute: Improve documentation. + * lib/attribute.h: Clarify where to place the various attributes. + 2024-07-30 Bruno Haible Reenable use of attributes in bracket syntax [[...]] (regr. yesterday). diff --git a/lib/attribute.h b/lib/attribute.h index 604965a6d1..186faa5526 100644 --- a/lib/attribute.h +++ b/lib/attribute.h @@ -20,12 +20,49 @@ /* Provide public ATTRIBUTE_* names for the private _GL_ATTRIBUTE_* macros used within Gnulib. */ -/* These attributes can be placed in two ways: - - At the start of a declaration (i.e. even before storage-class - specifiers!); then they apply to all entities that are declared - by the declaration. - - Immediately after the name of an entity being declared by the - declaration; then they apply to that entity only. */ +/* The placement of these attributes depends on the kind of declaration + and, in some cases, also on the programming language (C vs. C++). + + In function declarations and function definitions: + + * ATTRIBUTE_NOTHROW must come after the parameter list. + + * The macros + ATTRIBUTE_CONST + ATTRIBUTE_PURE + DEPRECATED + MAYBE_UNUSED + NODISCARD + REPRODUCIBLE + UNSEQUENCED + must come before the return type, and more precisely: + - In a function declaration/definition without a storage-class + specifier: at the beginning of the declaration/definition. + - In a function declaration/definition with a storage-class + specifier: + - In C: before the storage-class specifier. + - In C++: between the storage-class specifier and the return type. + + * The other macros can be placed + - Either + - In a function declaration/definition without a storage-class + specifier: at the beginning of the declaration/definition. + - In a function declaration/definition with a storage-class + specifier: between the storage-class specifier and the return + type. + - Or after the parameter list, + ∙ but after ATTRIBUTE_NOTHROW if present. + + In other declarations, such as variable declarations: + + * Either + - In C: before the storage-class specifier. + - In C++: between the storage-class specifier and the return type. + Then they apply to all entities that are declared by the declaration. + + * Or immediately after the name of an entity being declared by the + declaration. Then they apply to that entity only. + */ #ifndef _GL_ATTRIBUTE_H #define _GL_ATTRIBUTE_H -- 2.39.5