Re: [doc PATCH] update attribute docs for C++

[Sandra Loosemore <sandra@codesourcery.com>]

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