]> Savannah Git Hosting - gnulib.git/commitdiff
attribute: Improve documentation.
authorBruno Haible <bruno@clisp.org>
Tue, 30 Jul 2024 20:01:27 +0000 (22:01 +0200)
committerBruno Haible <bruno@clisp.org>
Tue, 30 Jul 2024 20:01:27 +0000 (22:01 +0200)
* lib/attribute.h: Clarify where to place the various attributes.

ChangeLog
lib/attribute.h

index 6bf78d04ffefaa126417a2d2d33e90ae8083a50e..872cc0f6cb2790dc8faf50406a8c6eef7513b3c2 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2024-07-30  Bruno Haible  <bruno@clisp.org>
+
+       attribute: Improve documentation.
+       * lib/attribute.h: Clarify where to place the various attributes.
+
 2024-07-30  Bruno Haible  <bruno@clisp.org>
 
        Reenable use of attributes in bracket syntax [[...]] (regr. yesterday).
index 604965a6d1821e999fdf3a4e167b290fe2e5fe58..186faa552658bb5e8349c64f42f037122f167ac4 100644 (file)
 /* 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