On 5/9/20 8:46 AM, Bruno Haible wrote: > 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.
Thanks, that's a good idea and makes attribute.h easier to use. I went through the comments and tweaked them in a way that I hope makes them even clearer. > Btw, why is there 'ATTRIBUTE_DEPRECATED', when there is also 'DEPRECATED', > defined in the same file and with the same definition? That's an oversight; I didn't notice the duplication. Thanks for mentioning it. I installed the attached patch to implement the above.
>From 1e7b424f62d431fffc2ad1c7d84effc3314860c2 Mon Sep 17 00:00:00 2001 From: Paul Eggert <egg...@cs.ucla.edu> Date: Sat, 9 May 2020 12:00:08 -0700 Subject: [PATCH] attribute: remove ATTRIBUTE_DEPRECATED * lib/attribute.h: Improve recently-added comments, mostly by shortening them (use active voice, etc.). (ATTRIBUTE_DEPRECATED): Remove, as it duplicates DEPRECATED. Problem reported by Bruno Haible in: https://lists.gnu.org/r/bug-gnulib/2020-05/msg00089.html --- ChangeLog | 9 +++ lib/attribute.h | 161 +++++++++++++++++++----------------------------- 2 files changed, 74 insertions(+), 96 deletions(-) diff --git a/ChangeLog b/ChangeLog index e259be6e4..c35cfee97 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2020-05-09 Paul Eggert <egg...@cs.ucla.edu> + + attribute: remove ATTRIBUTE_DEPRECATED + * lib/attribute.h: Improve recently-added comments, mostly + by shortening them (use active voice, etc.). + (ATTRIBUTE_DEPRECATED): Remove, as it duplicates DEPRECATED. + Problem reported by Bruno Haible in: + https://lists.gnu.org/r/bug-gnulib/2020-05/msg00089.html + 2020-05-09 Bruno Haible <br...@clisp.org> attribute: Add comments. diff --git a/lib/attribute.h b/lib/attribute.h index 22416a82f..3bd23faae 100644 --- a/lib/attribute.h +++ b/lib/attribute.h @@ -34,8 +34,7 @@ /* 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. */ +/* Warn if the entity is used. */ /* Applies to: - function, variable, - struct, union, struct/union member, @@ -44,13 +43,12 @@ 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. */ +/* Do not warn if control flow falls through 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. */ +/* Do not warn if the entity is not used. */ /* Applies to: - function, variable, - struct, union, struct/union member, @@ -59,8 +57,8 @@ 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. */ +/* Warn if the caller does not use the return value, + unless the caller uses something like ignore_value. */ /* Applies to: function, enumeration, class. */ #define NODISCARD _GL_ATTRIBUTE_NODISCARD @@ -71,141 +69,112 @@ 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 */ +/* ATTRIBUTE_ALLOC_SIZE ((N)) - The Nth argument of the function + is the size of the returned memory block. + ATTRIBUTE_ALLOC_SIZE ((M, N)) - Multiply the Mth and Nth arguments + to determine the size of the returned memory block. */ +/* Applies to: function, pointer to function, 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 */ +/* Always inline the function, and report an error if the compiler + cannot inline. */ +/* Applies to: function. */ #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 */ +/* Omit the function from stack traces when debugging. */ +/* Applies to: function. */ #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 */ +/* The function is rarely 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 */ +/* The function neither depends on nor affects observable state, + and always returns a value. Compilers can omit duplicate calls with + the same arguments. (This attribute is stricter than ATTRIBUTE_PURE.) */ +/* 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 */ +/* If a function call is not optimized way, report an error with 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 */ +/* Make the entity visible to debuggers etc., even with '-fwhole-program'. */ +/* Applies to: functions, variables. */ #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: +/* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) - + The STRING-INDEXth function argument is a format string of style + ARCHETYPE, which is 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 */ + If FIRST-TO-CHECK is not 0, arguments starting at FIRST-TO_CHECK + 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 */ +/* If called from some other compilation unit, the function executes + code from that unit only by return or by exception handling, + letting the compiler optimize that unit more aggressively. */ +/* 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 */ +/* Pointers to the type may point to the same storage as pointers to + other types, thus disabling strict aliasing optimization. */ +/* 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 */ +/* 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 */ +/* Do not inline the function. */ +/* 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 */ +/* ATTRIBUTE_NONNULL ((N1, N2,...)) - Arguments N1, N2,... must not be NULL. + ATTRIBUTE_NONNULL () - All pointer arguments must not be null. */ +/* 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. */ +/* 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 */ +/* 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. */ +/* For struct members: The member has the smallest possible alignment. + For struct, union, class: All members have the smallest possible alignment, + minimizing the memory required. */ /* 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 */ +/* The function does not affect observable state, and always returns a value. + Compilers can omit duplicate calls with the same arguments if + observable state is not changed between calls. (This attribute is + looser than ATTRIBUTE_CONST.) */ +/* Applies to: functions. */ #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE -/* Specifies that the function's return value is a non-NULL pointer. */ -/* Applies to: functions */ +/* 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 */ +/* The variadic function expects a trailing NULL argument. + ATTRIBUTE_SENTINEL () - The last argument is NULL. + ATTRIBUTE_SENTINEL ((N)) - The (N+1)st argument from the end is 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 */ +/* If a function call is not optimized way, warn with MSG. */ +/* Applies to: functions. */ #define ATTRIBUTE_WARNING(msg) _GL_ATTRIBUTE_WARNING (msg) -- 2.17.1
