bug-gnulib
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: documentation structure (was: attribute: add comments)


From: Bruno Haible
Subject: Re: documentation structure (was: attribute: add comments)
Date: Sun, 10 May 2020 22:24:42 +0200
User-agent: KMail/5.1.3 (Linux/4.4.0-177-generic; KDE/5.18.0; x86_64; ; )

Hi Paul,

> ATTRIBUTE_NONNULL is not merely about compiler diagnostics; it's also
> about optimization. Similarly for ATTRIBUTE_RETURNS_NONNULL (which I think was
> primarily motivated by optimization).

OK, let me tweak the comment (patch below).

> Conversely, ATTRIBUTE_PURE,
> ATTRIBUTE_CONST and ATTRIBUTE_LEAF are about diagnostics as well as being 
> about
> optimization.

Huh? I view ATTRIBUTE_PURE, ATTRIBUTE_CONST as mainly an optimization hint. They
produce diagnostics only if the attribute has been misplaced, or you can let
the compiler suggest to you where these attribute would make sense. But what
would be the diagnostics that are useful to the developer, independently of
optimization?

And for ATTRIBUTE_LEAF, I cannot imagine any useful diagnostics at all, since
the attribute is meant to be used in the compilation units that don't contain
the definition of said function.

> The section "Attributes for specific kinds of functions" is only about 
> compiler
> diagnostics

True. But it is about kinds of functions that are so rare (probably less than 2%
of all functions). The intent of having it in a separate section is that the
reader can rapidly skip this section when it's not interesting to them.

> I would replace "Attributes that make invalid code valid" to "Attributes for
> extensions to C".

Well, all the macros starting with ATTRIBUTE_, from __attribute__((__malloc__))
to __attribute__((__nothrow__)), are extensions to C. You see the ambiguity?

Also, the reader would be a "standards lawyer" (familiar with the way standards
are usually written) in order to understand what you mean by "extensions to C".
Whereas, I think, "make invalid code valid" is more directly to the point.

Similarly, when I had wording regarding "side effects" and you replaced it
with "observable state": I think "observable state" is a term from the
standards, but ask a computer science junior what "observable state" is?
I bet the term "side effects" is generally more understood.

Bruno


diff --git a/lib/attribute.h b/lib/attribute.h
index e9a81bb..d8d6286 100644
--- a/lib/attribute.h
+++ b/lib/attribute.h
@@ -88,7 +88,8 @@
 
 /* ================== Attributes for compiler diagnostics ================== */
 
-/* Attributes that help the compiler diagnose programmer mistakes.  */
+/* Attributes that help the compiler diagnose programmer mistakes.
+   Some of them may also help for some compiler optimizations.  */
 
 /* ATTRIBUTE_FORMAT ((ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)) -
    The STRING-INDEXth function argument is a format string of style




reply via email to

[Prev in Thread] Current Thread [Next in Thread]