[PATCH] attribute: improve comments

[Paul Eggert]

* lib/attribute.h: Update comments to better reflect what
GCC actually does with pure and const functions.
---
 ChangeLog       |  6 +++++
 lib/attribute.h | 64 +++++++++++++++++++++++++++++--------------------
 2 files changed, 44 insertions(+), 26 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index fdd53862e7..7d9726d61c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2024-06-03  Paul Eggert  <eggert@cs.ucla.edu>
+
+       attribute: improve comments
+       * lib/attribute.h: Update comments to better reflect what
+       GCC actually does with pure and const functions.
+
 2024-06-03  Bruno Haible  <bruno@clisp.org>
 
        acl-permissions: Fix test-file-has-acl-2.sh failure on Cygwin.
diff --git a/lib/attribute.h b/lib/attribute.h
index a7076c8b7e..604965a6d1 100644
--- a/lib/attribute.h
+++ b/lib/attribute.h
@@ -49,8 +49,9 @@
    _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_MAY_ALIAS, _GL_ATTRIBUTE_MAYBE_UNUSED,
    _GL_ATTRIBUTE_NODISCARD, _GL_ATTRIBUTE_NOINLINE, _GL_ATTRIBUTE_NONNULL,
    _GL_ATTRIBUTE_NONSTRING, _GL_ATTRIBUTE_NOTHROW, _GL_ATTRIBUTE_PACKED,
-   _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_RETURNS_NONNULL,
-   _GL_ATTRIBUTE_SENTINEL.  */
+   _GL_ATTRIBUTE_PURE, _GL_ATTRIBUTE_REPRODUCIBLE,
+   _GL_ATTRIBUTE_RETURNS_NONNULL, _GL_ATTRIBUTE_SENTINEL,
+   _GL_ATTRIBUTE_UNSEQUENCED.  */
 #if !_GL_CONFIG_H_INCLUDED
  #error "Please include config.h first."
 #endif
@@ -88,7 +89,7 @@
    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.  */
+/* Applies to: functions, pointer to functions, function types.  */
 #define ATTRIBUTE_ALLOC_SIZE(args) _GL_ATTRIBUTE_ALLOC_SIZE (args)
 
 /* ATTRIBUTE_DEALLOC (F, I) declares that the function returns pointers
@@ -170,7 +171,7 @@
 /* Attributes regarding debugging information emitted by the compiler.  */
 
 /* Omit the function from stack traces when debugging.  */
-/* Applies to: function.  */
+/* Applies to: functions.  */
 #define ATTRIBUTE_ARTIFICIAL _GL_ATTRIBUTE_ARTIFICIAL
 
 /* Make the entity visible to debuggers etc., even with '-fwhole-program'.  */
@@ -192,51 +193,62 @@
 
 /* Always inline the function, and report an error if the compiler
    cannot inline.  */
-/* Applies to: function.  */
+/* Applies to: functions.  */
 #define ATTRIBUTE_ALWAYS_INLINE _GL_ATTRIBUTE_ALWAYS_INLINE
 
-/* It is OK for a compiler to omit duplicate calls to the function with the
-   same arguments.
+/* It is OK for a compiler to move calls to the function and to omit
+   calls to the function if another call has the same arguments or the
+   result is not used.
    This attribute is safe for a function that neither depends on
-   nor affects observable state, and always returns exactly once -
-   e.g., does not loop forever, and does not call longjmp.
-   (This attribute is stricter than ATTRIBUTE_PURE.  It is equivalent to
-   UNSEQUENCED for a function that has no pointer or array parameters.)  */
+   nor affects state, and always returns exactly once -
+   e.g., does not raise an exception, call longjmp, or loop forever.
+   (This attribute is stricter than ATTRIBUTE_PURE because the
+   function cannot observe state.  It is stricter than UNSEQUENCED
+   because the function must return exactly once and cannot depend on
+   state addressed by its arguments.)  */
 /* Applies to: functions.  */
 #define ATTRIBUTE_CONST _GL_ATTRIBUTE_CONST
 
 /* It is OK for a compiler to move calls to the function and to omit duplicate
-   calls to the function with the same arguments.
+   calls to the function with the same arguments, so long as the state
+   addressed by its arguments is the same.
    This attribute is safe for a function that is effectless, idempotent,
    stateless, and independent; see ISO C 23 § 6.7.12.7 for a definition of
    these terms.
-   (This attribute is stricter than REPRODUCIBLE.  It is equivalent to
-   ATTRIBUTE_CONST for a function that has no pointer or array parameters.)
+   (This attribute is stricter than REPRODUCIBLE because the function
+   must be stateless and independent.  It is looser than ATTRIBUTE_CONST
+   because the function need not return exactly once and can depend
+   on state addressed by its arguments.)
    See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
    <https://stackoverflow.com/questions/76847905/>.  */
-/* Applies to: functions.  */
+/* Applies to: functions, pointer to functions, function type.  */
 #define UNSEQUENCED _GL_ATTRIBUTE_UNSEQUENCED
 
-/* It is OK for a compiler to omit duplicate calls to the function with the 
same
-   arguments if observable state is not changed between calls.
+/* It is OK for a compiler to move calls to the function and to omit
+   calls to the function if another call has the same arguments or the
+   result is not used, and if observable state is the same.
    This attribute is safe for a function that does not affect observable state
    and always returns exactly once.
-   (This attribute is looser than ATTRIBUTE_CONST.  It is equivalent to
-   REPRODUCIBLE for a function for which all pointer or array parameters have
-   'const'-qualified target types.)  */
+   (This attribute is looser than ATTRIBUTE_CONST because the function
+   can depend on observable state.  It is stricter than REPRODUCIBLE
+   because the function must return exactly once and cannot affect
+   state addressed by its arguments.)  */
 /* Applies to: functions.  */
 #define ATTRIBUTE_PURE _GL_ATTRIBUTE_PURE
 
-/* It is OK for a compiler to omit duplicate calls to the function with the 
same
-   arguments if observable state is not changed between calls.
+/* It is OK for a compiler to move calls to the function and to omit duplicate
+   calls to the function with the same arguments, so long as the state
+   addressed by its arguments is the same and is updated in time for
+   the rest of the program.
    This attribute is safe for a function that is effectless and idempotent; see
    ISO C 23 § 6.7.12.7 for a definition of these terms.
-   (This attribute is looser than UNSEQUENCED.  It is equivalent to
-   ATTRIBUTE_PURE for a function for which all pointer or array parameters have
-   'const'-qualified target types.)
+   (This attribute is looser than UNSEQUENCED because the function need
+   not be stateless and idempotent.  It is looser than ATTRIBUTE_PURE
+   because the function need not return exactly once and can affect
+   state addressed by its arguments.)
    See also <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2956.htm> and
    <https://stackoverflow.com/questions/76847905/>.  */
-/* Applies to: functions.  */
+/* Applies to: functions, pointer to functions, function type.  */
 #define REPRODUCIBLE _GL_ATTRIBUTE_REPRODUCIBLE
 
 /* The function is rarely executed.  */
-- 
2.43.0