[doc] update attribute docs for C++

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

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?

> +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.

> +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?

>  @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"?
>  
> +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/

>  
>  You may specify type attributes in an enum, struct or union type
>  declaration or definition by placing them immediately after the

-Sandra

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

On 12/4/18 9:26 AM, Martin Sebor wrote:
> 
> Thanks for the comments.  Attached is an updated patch with
> the typos fixed.  I've left the rest as is.

Well, I still think a number of points I commented on before need to be 
clarified in the text.  If I'm confused, I think other readers will be, 
too, and users shouldn't have to search for discussion on gcc-patches to 
figure out what the manual means.

> +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.

Like this paragraph above.  Users may read that first sentence and think 
they can attach function attributes to parameter declarations.  I'd 
suggest rewriting this as

"function attributes that specify properties of the function's 
parameters, like @code{nonnull}, also apply...."

or something like that.

> +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.
> +

And similarly here, but this is even more confusing.  What function 
attributes apply to variables, and not just parameters?  Given this is 
the variable attribute section, I think it would be more useful to say 
something about how you attach a variable attribute to the "this" 
parameter, rather than talking about function 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.

And here I would really prefer to use standard terminology than trying 
to inaccurately summarize what the terminology means.  E.g.

"...whether or not a class is trivial (in the C++11 sense) or POD (in 
C++98)."

-Sandra

On 12/4/18 2:04 PM, Sandra Loosemore wrote:
> On 12/4/18 9:26 AM, Martin Sebor wrote:
>>
>> Thanks for the comments.  Attached is an updated patch with
>> the typos fixed.  I've left the rest as is.
> 
> Well, I still think a number of points I commented on before need to be 
> clarified in the text.  If I'm confused, I think other readers will be, 
> too, and users shouldn't have to search for discussion on gcc-patches to 
> figure out what the manual means.
> 
>> +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.
> 
> Like this paragraph above.  Users may read that first sentence and think 
> they can attach function attributes to parameter declarations.  I'd 
> suggest rewriting this as
> 
> "function attributes that specify properties of the function's 
> parameters, like @code{nonnull}, also apply...."
> 
> or something like that.

I've adjusted the words to hopefully make this clearer.  I've added
a new term: /positional argument/ and used it to avoid the confusion.
There is unfortunately no good example to use here because the this
pointer is not a valid argument to any such attribute.  All but
nonnull trigger a warning when applied to this.  It's only important
to discuss because position 1 refers to it and the remaining arguments
in a member function start at position 2.

(I also noticed that the text referred to "attribute declarations"
so I changed those to "attribute specifications.")

>> +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.
>> +
> 
> And similarly here, but this is even more confusing.  What function 
> attributes apply to variables, and not just parameters?  Given this is 
> the variable attribute section, I think it would be more useful to say 
> something about how you attach a variable attribute to the "this" 
> parameter, rather than talking about function attributes.

This didn't come out quite right.  The intent is to make it clear
that variable attributes that apply to pointers can also be used
with references (to pointers or to other types), and ditto for
structs and classes (see the questions below).  Perhaps adding
the clarification isn't helpful here so I've removed it.

>> +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.
> 
> And here I would really prefer to use standard terminology than trying 
> to inaccurately summarize what the terminology means.  E.g.
> 
> "...whether or not a class is trivial (in the C++11 sense) or POD (in 
> C++98)."

This doesn't say what we want to say (nor is it accurate).

Here are the user's questions again:

   The documentation should clarify how it handles structs/
   classes/unions and references.  Does it threat references
   like pointers? Does it only allow PODs/trivial types to be
   returned, or does it invoke the copy constructor, when it
   is used again?

They were about const/pure but the same questions could be asked
about other attributes as well.  The simple answer I'm trying to
give is that it doesn't matter: (unless the manual says otherwise)
references [to pointers] are treated the same as pointers, and
there is no difference between functions that take arguments or
return classes with user-defined ctors and plain old C structs,
or between attributes applied to such types.  It doesn't help
to use C++ standard terms when they are subtly or substantially
different between C++ revisions, and then try to draw
a distinction between those different terms, when they don't
matter.

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 266799)
+++ 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
-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}).
+In GNU C and C++, you can use function attributes to specify certain
+function properties that may help the compiler optimize calls or
+check code more carefully for correctness.  For example, you
+can use attributes to specify that a function never returns
+(@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,19 +2345,34 @@ 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
-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
-declarations of the same function are merged.  An attribute specification
-that is not compatible with attributes already applied to a declaration
-of the same function is ignored with a warning.
+in the declaration of a function, 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 one attribute specification with another.
+@xref{Attribute Syntax}, for the exact rules on attribute syntax and
+placement.  Compatible attribute specifications on distinct declarations
+of the same function are merged.  An attribute specification that is not
+compatible with attributes already applied to a declaration of the same
+function is ignored with a warning.
 
+Some function attributes take one or more arguments that refer to
+the function's parameters by their positions within the function parameter
+list.  Such attribute arguments are referred to as @dfn{positional arguments}.
+Unless specified otherwise, positional arguments that specify properties
+of pointer types can also specify the same properties for the implicit C++
+@code{this} argument in non-static member functions, and, to parameters of
+reference to a pointer type.  For ordinary functions, position one refers
+to the first parameter on the list.  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}),
@@ -6127,13 +6143,13 @@ 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
@@ -7086,17 +7102,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

On 12/4/18 8:13 PM, Martin Sebor wrote:
> On 12/4/18 2:04 PM, Sandra Loosemore wrote:
>> On 12/4/18 9:26 AM, Martin Sebor wrote:
>>>
>>> [snip]
>>>
>>> +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.
>>
>> And here I would really prefer to use standard terminology than trying 
>> to inaccurately summarize what the terminology means.  E.g.
>>
>> "...whether or not a class is trivial (in the C++11 sense) or POD (in 
>> C++98)."
> 
> This doesn't say what we want to say (nor is it accurate).
> 
> Here are the user's questions again:
> 
>    The documentation should clarify how it handles structs/
>    classes/unions and references.  Does it threat references
>    like pointers? Does it only allow PODs/trivial types to be
>    returned, or does it invoke the copy constructor, when it
>    is used again?
> 
> They were about const/pure but the same questions could be asked
> about other attributes as well.  The simple answer I'm trying to
> give is that it doesn't matter: (unless the manual says otherwise)
> references [to pointers] are treated the same as pointers, and
> there is no difference between functions that take arguments or
> return classes with user-defined ctors and plain old C structs,
> or between attributes applied to such types.  It doesn't help
> to use C++ standard terms when they are subtly or substantially
> different between C++ revisions, and then try to draw
> a distinction between those different terms, when they don't
> matter.

I'm getting even more confused about what you're trying to communicate 
here.  :-(

What is the "it" referenced in the user's questions you quoted?  The 
const/pure attributes?  Those are function attributes.  The text you are 
adding is in the type attribute section, so it seemed like it was trying 
to address a different problem: stating that you can attach type 
attributes to any struct/class type whether or not it is a "trivial" 
class, by some definition of that term.  If that's not the purpose of 
this paragraph, what is it?

-Sandra

On 12/4/18 8:49 PM, Sandra Loosemore wrote:
> On 12/4/18 8:13 PM, Martin Sebor wrote:
>> On 12/4/18 2:04 PM, Sandra Loosemore wrote:
>>> On 12/4/18 9:26 AM, Martin Sebor wrote:
>>>>
>>>> [snip]
>>>>
>>>> +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.
>>>
>>> And here I would really prefer to use standard terminology than 
>>> trying to inaccurately summarize what the terminology means.  E.g.
>>>
>>> "...whether or not a class is trivial (in the C++11 sense) or POD (in 
>>> C++98)."
>>
>> This doesn't say what we want to say (nor is it accurate).
>>
>> Here are the user's questions again:
>>
>>    The documentation should clarify how it handles structs/
>>    classes/unions and references.  Does it threat references
>>    like pointers? Does it only allow PODs/trivial types to be
>>    returned, or does it invoke the copy constructor, when it
>>    is used again?
>>
>> They were about const/pure but the same questions could be asked
>> about other attributes as well.  The simple answer I'm trying to
>> give is that it doesn't matter: (unless the manual says otherwise)
>> references [to pointers] are treated the same as pointers, and
>> there is no difference between functions that take arguments or
>> return classes with user-defined ctors and plain old C structs,
>> or between attributes applied to such types.  It doesn't help
>> to use C++ standard terms when they are subtly or substantially
>> different between C++ revisions, and then try to draw
>> a distinction between those different terms, when they don't
>> matter.
> 
> I'm getting even more confused about what you're trying to communicate 
> here.  :-(

I explained the intent above:  "The simple answer I'm trying to
give is that [whether an attribute applies to a struct or a C++
class] doesn't matter."

It's really that simple so I'm not sure why we are spending so
much time on it.  Far more time even than it took me to explain
it to the user.

> What is the "it" referenced in the user's questions you quoted?  The 
> const/pure attributes?  Those are function attributes.  The text you are 
> adding is in the type attribute section, so it seemed like it was trying 
> to address a different problem: stating that you can attach type 
> attributes to any struct/class type whether or not it is a "trivial" 
> class, by some definition of that term.  If that's not the purpose of 
> this paragraph, what is it?

Again: the purpose is to explain that it doesn't matter whether
an attribute applies to a struct or a C++ class with ctors, in
any context with any attribute, either function, or variable,
or even type(*).

I answered the user's question below (and I CC'd you on it for
context):

   https://gcc.gnu.org/ml/gcc/2018-11/msg00146.html

The "it" in the question refers to GCC in the context of
the const and pure attributes.  As I explained above, the same
question could be asked about other attributes, including type
attributes.  The manual has historically referred to C structs
and hasn't consistently mentioned C++ classes so I can see how
someone might wonder if they are treated differently.
The purpose of this change is to make it clear that they
are not.

Martin

[*] For instance, that the effect of the attribute here:

   struct __attribute__ ((aligned (32))) A
   {
     int i;
   };

is the same as its effect here:

   class __attribute__ ((aligned (32))) B
   {
   public:
     B ();
     ~B ();
     int i;
   };

The description of the aligned attribute in the Common Type
Attributes chapter of the manual refers to "the alignment of
any given struct or union type" and doesn't mention classes,
so one might wonder whether the attribute has a different
effect on those.  Note that this is in contrast to the packed
attribute in the same chapter which does mention C++ classes:

   This attribute, attached to a struct, union, or C++ class
   type definition, ...

To make things clear, we could (and at some point perhaps
should) also go and edit all the places that talk about
structs and unions and mention C++ classes.  It won't
unambiguously answer the user's question about PODs vs
non-trivial classes with ctors, but it would help.

On 12/5/18 10:14 AM, Martin Sebor wrote:
> On 12/4/18 8:49 PM, Sandra Loosemore wrote:
> 
>> What is the "it" referenced in the user's questions you quoted?  The 
>> const/pure attributes?  Those are function attributes.  The text you 
>> are adding is in the type attribute section, so it seemed like it was 
>> trying to address a different problem: stating that you can attach 
>> type attributes to any struct/class type whether or not it is a 
>> "trivial" class, by some definition of that term.  If that's not the 
>> purpose of this paragraph, what is it?
> 
> Again: the purpose is to explain that it doesn't matter whether
> an attribute applies to a struct or a C++ class with ctors, in
> any context with any attribute, either function, or variable,
> or even type(*).

OK.  My main concern is that I think a user looking up a specific 
function or variable attribute is unlikely to think of reading through 
the type attribute section for that particular tidbit of information. 
Maybe we need to do some larger reorganization of material to include an 
overview of attribute semantics as well as a section on attribute 
syntax, but TBH I'm not enthusiastic about tackling that rewrite at the 
moment.  :-P

> To make things clear, we could (and at some point perhaps
> should) also go and edit all the places that talk about
> structs and unions and mention C++ classes.  It won't
> unambiguously answer the user's question about PODs vs
> non-trivial classes with ctors, but it would help.

I think it would be good to open an issue for a general review of this. 
I just recently fixed the specific instance of it for the packed 
attribute (PR 25759).

Going back to the last version of the patch posted, I have a couple nits 
about your newly added section of text:

> +Some function attributes take one or more arguments that refer to
> +the function's parameters by their positions within the function parameter
> +list.  Such attribute arguments are referred to as @dfn{positional arguments}.
> +Unless specified otherwise, positional arguments that specify properties
> +of pointer types can also specify the same properties for the implicit C++

I think this should be

s/properties of pointer types/properties of parameters with pointer types/

> +@code{this} argument in non-static member functions, and, to parameters of

s/and, to parameters of/and to parameters with/

> +reference to a pointer type.  For ordinary functions, position one refers
> +to the first parameter on the list.  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}),

I think the patch is OK to commit with those changes.

-Sandra

On 12/11/18 9:41 PM, Sandra Loosemore wrote:
> On 12/5/18 10:14 AM, Martin Sebor wrote:
>> On 12/4/18 8:49 PM, Sandra Loosemore wrote:
>>
>>> What is the "it" referenced in the user's questions you quoted?  The 
>>> const/pure attributes?  Those are function attributes.  The text you 
>>> are adding is in the type attribute section, so it seemed like it was 
>>> trying to address a different problem: stating that you can attach 
>>> type attributes to any struct/class type whether or not it is a 
>>> "trivial" class, by some definition of that term.  If that's not the 
>>> purpose of this paragraph, what is it?
>>
>> Again: the purpose is to explain that it doesn't matter whether
>> an attribute applies to a struct or a C++ class with ctors, in
>> any context with any attribute, either function, or variable,
>> or even type(*).
> 
> OK.  My main concern is that I think a user looking up a specific 
> function or variable attribute is unlikely to think of reading through 
> the type attribute section for that particular tidbit of information. 
> Maybe we need to do some larger reorganization of material to include an 
> overview of attribute semantics as well as a section on attribute 
> syntax, but TBH I'm not enthusiastic about tackling that rewrite at the 
> moment.  :-P

I also think that the attribute documentation could stand to be
restructured.  A number of attributes either already are or should
be documented in all three sections, which leads to quite a bit
of duplication (e.g., the alloc_size function attribute that
I have just duplicated in the other two section in this patch:
https://gcc.gnu.org/ml/gcc-patches/2018-12/msg00415.html)
I like the idea of a high-level overview of attributes of all
kinds.

>> To make things clear, we could (and at some point perhaps
>> should) also go and edit all the places that talk about
>> structs and unions and mention C++ classes.  It won't
>> unambiguously answer the user's question about PODs vs
>> non-trivial classes with ctors, but it would help.
> 
> I think it would be good to open an issue for a general review of this. 
> I just recently fixed the specific instance of it for the packed 
> attribute (PR 25759).

That sounds good to me.  I opened bug 88472.  I'm willing to
help with the review/restructuring.

> 
> Going back to the last version of the patch posted, I have a couple nits 
> about your newly added section of text:
> 
>> +Some function attributes take one or more arguments that refer to
>> +the function's parameters by their positions within the function 
>> parameter
>> +list.  Such attribute arguments are referred to as @dfn{positional 
>> arguments}.
>> +Unless specified otherwise, positional arguments that specify properties
>> +of pointer types can also specify the same properties for the 
>> implicit C++
> 
> I think this should be
> 
> s/properties of pointer types/properties of parameters with pointer types/
> 
>> +@code{this} argument in non-static member functions, and, to 
>> parameters of
> 
> s/and, to parameters of/and to parameters with/

Done.

> 
>> +reference to a pointer type.  For ordinary functions, position one 
>> refers
>> +to the first parameter on the list.  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}),
> 
> I think the patch is OK to commit with those changes.

Thanks. Committed in r267064.

Martin