This is the mail archive of the gcc-patches@gcc.gnu.org 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/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


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