[doc PATCH] update attribute docs for C++

[Martin Sebor <msebor@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 925 bytes --]

In a recent discussion a user asked us to clarify the effects
of attributes const and pure on member functoons of trivial
structs vs. non-trivial classes, and functions with pointer
vs. reference arguments.

I think this is worth explaining in some general statement
rather than for individual attributes.  The attached patch
adds words to document this for all function (and variable)
attributes.

While discussing C++ specifics I thought it would also be
helpful to mention in the same context that in C++ positional
arguments include the this pointer.

Finally, since in a separate change we are tweaking attributes
const and pure, I thought it would be appropriate to replace
the reference to attribute pure as one denoting a function
that "returns a value depending only its arguments" with one
to attribute const.  I think that's more accurate -- a pure
function may depend on the global state of the program.

Martin


[-- Attachment #2: gcc-doc-c-cxx-attributes.diff --]
[-- Type: text/x-patch, Size: 6712 bytes --]

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
+type.  In attributes that refer to function parameters by their position
+in the argument list the first pararameter 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}),
@@ -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
+type.
+
 @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
+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.  
+eclosed in double parentheses.
 
 You may specify type attributes in an enum, struct or union type
 declaration or definition by placing them immediately after the