This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
Re: [doc PATCH] update attribute docs for C++
On 12/4/18 12:09 AM, Sandra Loosemore wrote:
On 12/3/18 4:23 PM, Martin Sebor wrote:
gcc/ChangeLog:
* doc/extend.texi (attribute const, pure): Clarify.
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 266766)
+++ gcc/doc/extend.texi (working copy)
@@ -2276,12 +2276,13 @@ the enclosing block.
@cindex @code{volatile} applied to function
@cindex @code{const} applied to function
-In GNU C, you can use function attributes to declare certain things
-about functions called in your program which help the compiler
-optimize calls and check your code more carefully. For example, you
+In GNU C and C++, you can use function attributes to declare certain
+function properties that may help the compiler optimize calls or
+check code more carefully for correctness. For example, you
can use attributes to declare that a function never returns
-(@code{noreturn}), returns a value depending only on its arguments
-(@code{pure}), or has @code{printf}-style arguments (@code{format}).
+(@code{noreturn}), returns a value depending only on the values of
+its arguments (@code{const}), or has @code{printf}-style arguments
+(@code{format}).
You can also use attributes to control memory placement, code
generation options or call/return conventions within the function
@@ -2288,12 +2289,15 @@ generation options or call/return conventions
with
being annotated. Many of these attributes are target-specific. For
example, many targets support attributes for defining interrupt
handler functions, which typically must follow special register usage
-and return conventions.
+and return conventions. Such attributes are described in the subsection
+for each target. However, a considerable number of attributes are
+supported by most, if not all targets. Those are described in
+the @ref{Common Function Attributes} section.
Function attributes are introduced by the @code{__attribute__} keyword
-on a declaration, followed by an attribute specification inside double
-parentheses. You can specify multiple attributes in a declaration by
-separating them by commas within the double parentheses or by
+on a declaration, followed by an attribute specification enclosed in
+double parentheses. You can specify multiple attributes in a
declaration
+by separating them by commas within the double parentheses or by
immediately following an attribute declaration with another attribute
declaration. @xref{Attribute Syntax}, for the exact rules on attribute
syntax and placement. Compatible attribute specifications on distinct
@@ -2301,6 +2305,15 @@ declarations of the same function are merged. An
that is not compatible with attributes already applied to a declaration
of the same function is ignored with a warning.
+Unless specified otherwise, function attributes that apply to function
+parameters of pointer types also apply to the implicit C++ @code{this}
+argument in non-constant member functions, and to parameters of
reference
I'm confused by this. Function attributes apply to functions, not
parameters. Even if they did apply to parameters, why the restriction
against constant member functions?
The non-constant a typo. I meant to say non-static.
The part about parameters applies to attributes like nonnull that
attach to a function declaration but describe a property of
a positional parameter. (Nonnull should make it clear that it's
implicit for the first parameter of non-static member functions,
and GCC should probably issue a warning when it's specified since
it's likely due to a mistake/misunderstanding.)
+type. In attributes that refer to function parameters by their position
+in the argument list the first pararameter is at position one. In C++
s/pararameter/parameter
Again, I'm confused. Is this about the format attribute? It would be
far less obscure to just move this explanation to the discussion of that
attribute, because nobody trying to understand how the format attribute
works would be able to tie this discussion in another section into it.
Only a couple of attributes cover it: format and format_arg.
Alloc_align, alloc_size, nonnull, and sentinel don't. (I haven't
done a review of target function attributes to see if there are
any like that.) I wouldn't mind if the text were also duplicated
for each individual attribute, but because it's a general feature
of all such attributes I do think there needs to be a blanket
statement that stipulates this rule for all of them.
+non-static member functions position one refers to the implicit
@code{this}
+pointer. The same restrictions and effects apply to function attributes
+used with ordinary functions or C++ member functions.
+
GCC also supports attributes on
variable declarations (@pxref{Variable Attributes}),
labels (@pxref{Label Attributes}),
@@ -6067,18 +6080,23 @@ when this attribute is present.
@cindex attribute of variables
@cindex variable attributes
-The keyword @code{__attribute__} allows you to specify special
-attributes of variables or structure fields. This keyword is followed
-by an attribute specification inside double parentheses. Some
-attributes are currently defined generically for variables.
-Other attributes are defined for variables on particular target
-systems. Other attributes are available for functions
-(@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
+The keyword @code{__attribute__} allows you to specify special
properties
+of variables, function parameters, or structure, union, and, in C++,
class
+members. This @code{__attribute__} keyword is followed by an attribute
+specification enclosed in double parentheses. Some attributes are
currently
+defined generically for variables. Other attributes are defined for
+variables on particular target systems. Other attributes are available
+for functions (@pxref{Function Attributes}), labels (@pxref{Label
Attributes}),
enumerators (@pxref{Enumerator Attributes}), statements
(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
Other front ends might define more attributes
(@pxref{C++ Extensions,,Extensions to the C++ Language}).
+Unless specified otherwise, function attributes that apply to variables
+or function parameters of pointer types also apply to the implicit
C++ @code
+{this} argument in non-constant member functions, and to arguments of
reference
Please don't put a line break between the @code and its following "{".
+type.
+
Again, why are constant member functions special? Do you really mean to
say "non-static member functions" instead?
Yes, that's what I meant.
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
@@ -7026,17 +7044,21 @@ placed in either the @code{.bss_below100} section
@cindex attribute of types
@cindex type attributes
-The keyword @code{__attribute__} allows you to specify special
-attributes of types. Some type attributes apply only to @code{struct}
-and @code{union} types, while others can apply to any type defined
-via a @code{typedef} declaration. Other attributes are defined for
-functions (@pxref{Function Attributes}), labels (@pxref{Label
-Attributes}), enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}), and for
-variables (@pxref{Variable Attributes}).
+The keyword @code{__attribute__} allows you to specify various special
+properties of types. Some type attributes apply only to structure and
+and types, and in C++, also class types, while others can apply to any
s/structure and and types/structure and union types/
+type defined via a @code{typedef} declaration. Unless otherwise
+specified, the same restrictions and effects apply to attributes
regardless
+of whether a type is a trivial structure or a C++ class with
user-defined
+constructors, destructors, or a copy assignment.
Why pick out constructors, destructors, and copy assignment? Maybe you
are trying to say "whether or not a class is a POD type"?
User-defined ctors, dtors, and assignment operators are what most
commonly determines whether a class is trivial in the C++ 11 sense
(or POD in C++ 98) or not. There are other things that make a class
non-trivial but they're less common. We could just use the term POD
but that's more restrictive than trivial. We could also just use
the term trivial but that's a common English word that people may
not yet associate with the C++ 11 (and evolving) meaning. So to
try to make it clear I mentioned ctors etc. I don't insist on any
one of these, just explaining my choice and pointing out that none
of them is without problems. (The user on whose behalf I'm making
these changes was specifically asking about a distinction between
POD and trivial types but I don't think it's necessary to go into
as much detail).
+Other attributes are defined for functions (@pxref{Function
Attributes}),
+labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
+Attributes}), statements (@pxref{Statement Attributes}), and for
variables
+(@pxref{Variable Attributes}).
+
The @code{__attribute__} keyword is followed by an attribute
specification
-inside double parentheses. +eclosed in double parentheses.
s/eclosed/enclosed/
Thanks for the comments. Attached is an updated patch with
the typos fixed. I've left the rest as is.
Martin
gcc/ChangeLog:
* doc/extend.texi (Function Attributes): Clarify C++ aspects.
(Variable Attributes): Same.
(Type Attributes): Same.
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 266787)
+++ gcc/doc/extend.texi (working copy)
@@ -2332,12 +2332,13 @@ the enclosing block.
@cindex @code{volatile} applied to function
@cindex @code{const} applied to function
-In GNU C, you can use function attributes to declare certain things
-about functions called in your program which help the compiler
-optimize calls and check your code more carefully. For example, you
+In GNU C and C++, you can use function attributes to declare certain
+function properties that may help the compiler optimize calls or
+check code more carefully for correctness. For example, you
can use attributes to declare that a function never returns
-(@code{noreturn}), returns a value depending only on its arguments
-(@code{pure}), or has @code{printf}-style arguments (@code{format}).
+(@code{noreturn}), returns a value depending only on the values of
+its arguments (@code{const}), or has @code{printf}-style arguments
+(@code{format}).
You can also use attributes to control memory placement, code
generation options or call/return conventions within the function
@@ -2344,12 +2345,15 @@ generation options or call/return conventions with
being annotated. Many of these attributes are target-specific. For
example, many targets support attributes for defining interrupt
handler functions, which typically must follow special register usage
-and return conventions.
+and return conventions. Such attributes are described in the subsection
+for each target. However, a considerable number of attributes are
+supported by most, if not all targets. Those are described in
+the @ref{Common Function Attributes} section.
Function attributes are introduced by the @code{__attribute__} keyword
-on a declaration, followed by an attribute specification inside double
-parentheses. You can specify multiple attributes in a declaration by
-separating them by commas within the double parentheses or by
+on a declaration, followed by an attribute specification enclosed in
+double parentheses. You can specify multiple attributes in a declaration
+by separating them by commas within the double parentheses or by
immediately following an attribute declaration with another attribute
declaration. @xref{Attribute Syntax}, for the exact rules on attribute
syntax and placement. Compatible attribute specifications on distinct
@@ -2357,6 +2361,15 @@ declarations of the same function are merged. An
that is not compatible with attributes already applied to a declaration
of the same function is ignored with a warning.
+Unless specified otherwise, function attributes that apply to function
+parameters of pointer types also apply to the implicit C++ @code{this}
+argument in non-static member functions, and to parameters of reference
+type. In attributes that refer to function parameters by their position
+in the argument list the first parameter is at position one. In C++
+non-static member functions position one refers to the implicit @code{this}
+pointer. The same restrictions and effects apply to function attributes
+used with ordinary functions or C++ member functions.
+
GCC also supports attributes on
variable declarations (@pxref{Variable Attributes}),
labels (@pxref{Label Attributes}),
@@ -6123,18 +6136,23 @@ when this attribute is present.
@cindex attribute of variables
@cindex variable attributes
-The keyword @code{__attribute__} allows you to specify special
-attributes of variables or structure fields. This keyword is followed
-by an attribute specification inside double parentheses. Some
-attributes are currently defined generically for variables.
-Other attributes are defined for variables on particular target
-systems. Other attributes are available for functions
-(@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
+The keyword @code{__attribute__} allows you to specify special properties
+of variables, function parameters, or structure, union, and, in C++, class
+members. This @code{__attribute__} keyword is followed by an attribute
+specification enclosed in double parentheses. Some attributes are currently
+defined generically for variables. Other attributes are defined for
+variables on particular target systems. Other attributes are available
+for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}),
enumerators (@pxref{Enumerator Attributes}), statements
(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}).
Other front ends might define more attributes
(@pxref{C++ Extensions,,Extensions to the C++ Language}).
+Unless specified otherwise, function attributes that apply to variables
+or function parameters of pointer types also apply to the implicit C++
+@code {this} argument in non-static member functions, and to arguments of
+reference type.
+
@xref{Attribute Syntax}, for details of the exact syntax for using
attributes.
@@ -7082,17 +7100,21 @@ placed in either the @code{.bss_below100} section
@cindex attribute of types
@cindex type attributes
-The keyword @code{__attribute__} allows you to specify special
-attributes of types. Some type attributes apply only to @code{struct}
-and @code{union} types, while others can apply to any type defined
-via a @code{typedef} declaration. Other attributes are defined for
-functions (@pxref{Function Attributes}), labels (@pxref{Label
-Attributes}), enumerators (@pxref{Enumerator Attributes}),
-statements (@pxref{Statement Attributes}), and for
-variables (@pxref{Variable Attributes}).
+The keyword @code{__attribute__} allows you to specify various special
+properties of types. Some type attributes apply only to structure and
+union types, and in C++, also class types, while others can apply to
+any type defined via a @code{typedef} declaration. Unless otherwise
+specified, the same restrictions and effects apply to attributes regardless
+of whether a type is a trivial structure or a C++ class with user-defined
+constructors, destructors, or a copy assignment.
+Other attributes are defined for functions (@pxref{Function Attributes}),
+labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator
+Attributes}), statements (@pxref{Statement Attributes}), and for variables
+(@pxref{Variable Attributes}).
+
The @code{__attribute__} keyword is followed by an attribute specification
-inside double parentheses.
+enclosed in double parentheses.
You may specify type attributes in an enum, struct or union type
declaration or definition by placing them immediately after the