From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 101424 invoked by alias); 5 Dec 2018 03:14:01 -0000 Mailing-List: contact gcc-patches-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-patches-owner@gcc.gnu.org Received: (qmail 100851 invoked by uid 89); 5 Dec 2018 03:14:00 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-16.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3,RCVD_IN_DNSWL_NONE,SPF_PASS autolearn=ham version=3.3.2 spammy=threat, positions X-HELO: mail-qt1-f193.google.com Received: from mail-qt1-f193.google.com (HELO mail-qt1-f193.google.com) (209.85.160.193) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 05 Dec 2018 03:13:56 +0000 Received: by mail-qt1-f193.google.com with SMTP id t13so20754249qtn.3 for ; Tue, 04 Dec 2018 19:13:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-language; bh=mVLaFQfiMnq254oYLcl3PnyScwVkyFr8Pi2pxcBzbmY=; b=qQ0mYx7m1hvuRUmVEqleAKAFRwt8LCKD2gnKodP+dS4OM8pZO0SyUwKfD3+wPg3wYv 22WMajoqD0Mu32VibwH3E6GXRgSG2I4jIojXiSSZb44c1lt9SXpMF0kNQdHcl3OcCP9+ nwU6arVgUdn4auGkAbtGZ3cOrx/M3Y7+84/s/JMuo0Blj+w793qIw/u4Ztbo2a9tFPeT qb0Wl2pkn3fCIgfhabF6uVq8uk/Qn/QAT5XTiA7DystqYg53NXr/G1e770nWDWAXA4z3 tyvRnr5S9alArmqvW1jnCs+gu6XiZzBFTKp/IuFTh/HduwakU+SDV2ZYt0VlsRZS8+6G z6MQ== Return-Path: Received: from localhost.localdomain (97-118-99-160.hlrn.qwest.net. [97.118.99.160]) by smtp.gmail.com with ESMTPSA id z23sm16715729qkg.50.2018.12.04.19.13.52 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 04 Dec 2018 19:13:53 -0800 (PST) Subject: Re: [doc PATCH] update attribute docs for C++ To: Sandra Loosemore , Gcc Patch List References: <932d5110-020b-4814-c3e7-bcda8e9d28ec@codesourcery.com> <11cf135d-7524-ed3a-7cbb-a1c436b4c8ce@gmail.com> <96070396-369b-e736-72dc-e08ab46a847a@codesourcery.com> From: Martin Sebor Message-ID: <1bdd5657-1295-78a2-4299-21b3cc13af9c@gmail.com> Date: Wed, 05 Dec 2018 03:14:00 -0000 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.3.1 MIME-Version: 1.0 In-Reply-To: <96070396-369b-e736-72dc-e08ab46a847a@codesourcery.com> Content-Type: multipart/mixed; boundary="------------B603E5E73A5D022F84D1DD12" X-IsSubscribed: yes X-SW-Source: 2018-12/txt/msg00250.txt.bz2 This is a multi-part message in MIME format. --------------B603E5E73A5D022F84D1DD12 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 8bit Content-length: 4648 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 --------------B603E5E73A5D022F84D1DD12 Content-Type: text/x-patch; name="gcc-doc-c-cxx-attributes.diff" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="gcc-doc-c-cxx-attributes.diff" Content-length: 7074 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 --------------B603E5E73A5D022F84D1DD12--