Compiler Attributes: improve explanation of header

Explain better what "optional" attributes are, and avoid calling them so to avoid confusion. Simply retain "Optional" as a word to look for in the comments. Moreover, add a couple sentences to explain a bit more the intention and the documentation links.

Miguel Ojeda committed 8 years ago

Commit 24efee41 parent 8bd66d11 file · +9 −5Browse files

Unified · Split

include/linux/compiler_attributes.h+9−5

@@ -4,22 +4,26 @@ · 3 unmodified lines
4	4
5	5	/*
6	6	* The attributes in this file are unconditionally defined and they directly
7		− * map to compiler attribute(s) -- except those that are optional.
	7	+ * map to compiler attribute(s), unless one of the compilers does not support
	8	+ * the attribute. In that case, __has_attribute is used to check for support
	9	+ * and the reason is stated in its comment ("Optional: ...").
8	10	*
9	11	* Any other "attributes" (i.e. those that depend on a configuration option,
10	12	* on a compiler, on an architecture, on plugins, on other attributes...)
11	13	* should be defined elsewhere (e.g. compiler_types.h or compiler-*.h).
	14	+ * The intention is to keep this file as simple as possible, as well as
	15	+ * compiler- and version-agnostic (e.g. avoiding GCC_VERSION checks).
12	16	*
13	17	* This file is meant to be sorted (by actual attribute name,
14	18	* not by #define identifier). Use the __attribute__((__name__)) syntax
15	19	* (i.e. with underscores) to avoid future collisions with other macros.
16		− * If an attribute is optional, state the reason in the comment.
	20	+ * Provide links to the documentation of each supported compiler, if it exists.
17	21	*/
18	22
19	23	/*
20		− * To check for optional attributes, we use __has_attribute, which is supported
21		− * on gcc >= 5, clang >= 2.9 and icc >= 17. In the meantime, to support
22		− * 4.6 <= gcc < 5, we implement __has_attribute by hand.
	24	+ * __has_attribute is supported on gcc >= 5, clang >= 2.9 and icc >= 17.
	25	+ * In the meantime, to support 4.6 <= gcc < 5, we implement __has_attribute
	26	+ * by hand.
23	27	*
24	28	* sparse does not support __has_attribute (yet) and defines __GNUC_MINOR__
25	29	* depending on the compiler used to build it; however, these attributes have