Hi Paul,
I can't really comfortably use a set of macro, for which I need to look
up a C in-progress standard, a C++ standard, and the GCC documentation.
So, I've added documentation, that answers the questions:
- Where should the attribute be placed?
- On which entities is it supported?
- What is its use-case?
- What is the argument? Single parentheses or nested parentheses?
The text I wrote is meant be easier to understand upon first use, but
still as correct (or nearly as correct) as the corresponding GCC documentation.
Btw, why is there 'ATTRIBUTE_DEPRECATED', when there is also 'DEPRECATED',
defined in the same file and with the same definition?
2020-05-09 Bruno Haible <br...@clisp.org>
attribute: Add comments.
* lib/attribute.h: Document each macro.
diff --git a/lib/attribute.h b/lib/attribute.h
index a4e12df..22416a8 100644
--- a/lib/attribute.h
+++ b/lib/attribute.h
@@ -20,39 +20,193 @@
/* 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. */
+
#ifndef _GL_ATTRIBUTE_H
#define _GL_ATTRIBUTE_H
+
/* C2X standard attributes have macro names that do not begin with
'ATTRIBUTE_'. */
+
+/* Tells that the entity is deprecated. A use of the entity produces a
+ warning. */
+/* Applies to:
+ - function, variable,
+ - struct, union, struct/union member,
+ - enumeration, enumeration item,
+ - typedef,
+ in C++ also: namespace, class, template specialization. */
#define DEPRECATED _GL_ATTRIBUTE_DEPRECATED
+
+/* Tells that it's intentional that the control flow can go on to the
+ immediately following 'case' or 'default' label. */
+/* Applies to: Empty statement (;), inside a 'switch' statement. */
#define FALLTHROUGH _GL_ATTRIBUTE_FALLTHROUGH
+
+/* Tells that it's OK if the entity is not used. No "is not used" warning
+ shall be produced for the entity. */
+/* Applies to:
+ - function, variable,
+ - struct, union, struct/union member,
+ - enumeration, enumeration item,
+ - typedef,
+ in C++ also: class. */
#define MAYBE_UNUSED _GL_ATTRIBUTE_MAYBE_UNUSED
+
+/* Tells that it is important for the caller of a function to inspect its
+ return value. Discarding the return value produces a warning. */
+/* Applies to: function, enumeration, class. */
#define NODISCARD _GL_ATTRIBUTE_NODISCARD
+
/* Selected GCC attributes; see:
https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
+ https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
+ https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html
These names begin with 'ATTRIBUTE_' to avoid name clashes. */
+
+/* Used for memory allocation functions.
+ ATTRIBUTE_ALLOC_SIZE ((n)) specifies that the function returns a block
+ of memory whose size is the n-th argument (n counts from 1).
+ ATTRIBUTE_ALLOC_SIZE ((m, n)) specifies that the function returns a block
+ of memory whose size is the product of the m-th argument and the n-th
+ argument. */
+/* Applies to: functions, pointers to functions, function types */
#define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
+
+/* Forces the function to be inlined. Results in an error if the compiler
+ cannot honour the inlining request. */
+/* Applies to: functions */
#define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
+
+/* Used for small inline functions.
+ Specifies that the function should be omitted from stack traces. */
+/* Applies to: functions */
#define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
+
+/* Used to denote the result of manual profiling.
+ Specifies that the function is unlikely to be executed. */
+/* Applies to: functions */
#define ATTRIBUTE_COLD _GL_ATTRIBUTE_COLD
+
+/* Used on functions that don't inspect memory and don't do side effects
+ and don't invoke random behaviour.
+ Specifies that the compiler is allowed to replace multiple invocations
+ of the function with the same arguments with a single invocation. */
+/* Applies to: functions */
#define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
+
+/* Same as DEPRECATED, above. */
#define ATTRIBUTE_DEPRECATED _GL_ATTRIBUTE_DEPRECATED
+
+/* Used on functions that should not be called.
+ ATTRIBUTE_ERROR (MSG) specifies that the compiler is allowed to produce
+ an error when an invocation of the function cannot be optimized away.
+ The error message will include MSG. */
+/* Applies to: functions */
#define ATTRIBUTE_ERROR(msg) _GL_ATTRIBUTE_ERROR (msg)
+
+/* Used on functions or variables that shall persist across the
+ '-fwhole-program' optimization. */
+/* Applies to: functions */
#define ATTRIBUTE_EXTERNALLY_VISIBLE _GL_ATTRIBUTE_EXTERNALLY_VISIBLE
+
+/* Used on functions that consume arguments according to a format string.
+ ATTRIBUTE_FORMAT ((FORMAT-STRING-TYPE, FORMAT-STRING-ARGUMENT-NUMBER,
+ FIRST-CONSUMED-ARGUMENT-NUMBER))
+ specifies that the argument FORMAT-STRING-ARGUMENT-NUMBER is a format
string.
+ The syntax of this format string is described by FORMAT-STRING-TYPE, namely
+ one of:
+ printf, gnu_printf
+ scanf, gnu_scanf,
+ strftime, gnu_strftime,
+ strfmon,
+ or the same thing prefixed and suffixed with '__'.
+ If FIRST-CONSUMED-ARGUMENT-NUMBER is not 0, the compiler checks that the
+ arguments starting at FIRST-CONSUMED-ARGUMENT-NUMBER are suitable for the
+ format string. */
+/* Applies to: functions */
#define ATTRIBUTE_FORMAT(spec) _GL_ATTRIBUTE_FORMAT (spec)
+
+/* Specifies that the function does not - directly or indirectly - invoke any
+ code from the current compilation unit.
+ This attribute allows the compiler to do more aggressive optimizations on
+ the current compilation unit. */
+/* Applies to: functions */
#define ATTRIBUTE_LEAF _GL_ATTRIBUTE_LEAF
+
+/* Specifies that pointers to the type may point to the same storage as
+ pointers to other types.
+ This attribute disables compiler optimizations that are based on
+ "no aliasing" assumptions for the given type. */
+/* Applies to: types */
#define ATTRIBUTE_MAY_ALIAS _GL_ATTRIBUTE_MAY_ALIAS
+
+/* Used for memory allocation functions.
+ Specifies that the function returns a pointer to freshly allocated
+ memory. */
+/* Applies to: functions */
#define ATTRIBUTE_MALLOC _GL_ATTRIBUTE_MALLOC
+
+/* Specifies that the function should not be inlined. */
+/* Applies to: functions */
#define ATTRIBUTE_NOINLINE _GL_ATTRIBUTE_NOINLINE
+
+/* ATTRIBUTE_NONNULL ((ARGNO1, ARGNO2, ...)) specifies that the argument number
+ ARGNO1, the argument number ARGNO2, etc. must not be NULL pointers. */
+/* Applies to: functions */
#define ATTRIBUTE_NONNULL(args) _GL_ATTRIBUTE_NONNULL (args)
+
+/* Specifies that the contents of a character array is not meant to be NUL-
+ terminated. */
+/* Applies to: struct/union members and variables that are arrays of element
+ type '[[un]signed] char'. */
#define ATTRIBUTE_NONSTRING _GL_ATTRIBUTE_NONSTRING
+
+/* Specifies that the function does not throw exceptions. */
+/* Applies to: functions */
#define ATTRIBUTE_NOTHROW _GL_ATTRIBUTE_NOTHROW
+
+/* For struct members: Specifies that the struct member shall have the minimum
+ possible alignment.
+ For struct, union, class: Specifies that all members shall have the minimum
+ possible alignment, thus minimizing the memory size of the type. */
+/* Applies to: struct members, struct, union,
+ in C++ also: class. */
#define ATTRIBUTE_PACKED _GL_ATTRIBUTE_PACKED
+
+/* Used on functions that don't do side effects and don't invoke random
+ behaviour.
+ Specifies that the compiler is allowed to replace multiple invocations
+ of the function with the same arguments with a single invocation, if
+ there are no memory stores in between the invocations. */
+/* Applies to: functions */
#define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
+
+/* Specifies that the function's return value is a non-NULL pointer. */
+/* Applies to: functions */
#define ATTRIBUTE_RETURNS_NONNULL _GL_ATTRIBUTE_RETURNS_NONNULL
+
+/* Used on variadic functions.
+ ATTRIBUTE_SENTINEL () and ATTRIBUTE_SENTINEL (0) specify that the last
+ argument must be NULL.
+ ATTRIBUTE_SENTINEL (n) specifies that the (n+1)st argument from the end
+ must be NULL. */
+/* Applies to: functions */
#define ATTRIBUTE_SENTINEL(pos) _GL_ATTRIBUTE_SENTINEL (pos)
+
+/* Used on functions that should not be called.
+ ATTRIBUTE_WARNING (MSG) specifies that the compiler is allowed to produce
+ a warning when an invocation of the function cannot be optimized away.
+ The warning message will include MSG. */
+/* Applies to: functions */
#define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg)
+
#endif /* _GL_ATTRIBUTE_H */
