This is the mail archive of the mailing list for the GCC project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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

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:
I like the idea of a high-level overview of attributes of all

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/


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]