Re: [clang] 5c689e4 - Improve documentation for the [[clang::lifetimebound]] attribute.

2021-03-22 Thread Richard Smith via cfe-commits 
On Mon, 22 Mar 2021 at 13:31, David Blaikie  wrote:

> On Thu, Mar 18, 2021 at 7:58 PM Richard Smith via cfe-commits <
> cfe-commits@lists.llvm.org> wrote:
>
>>
>> Author: Richard Smith
>> Date: 2021-03-18T19:58:21-07:00
>> New Revision: 5c689e4bb0473e08645547ddbf9874b5e2fa04d0
>>
>> URL:
>> https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0
>> DIFF:
>> https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0.diff
>>
>> LOG: Improve documentation for the [[clang::lifetimebound]] attribute.
>>
>> Added:
>>
>>
>> Modified:
>> clang/include/clang/Basic/AttrDocs.td
>>
>> Removed:
>>
>>
>>
>>
>> 
>> diff  --git a/clang/include/clang/Basic/AttrDocs.td
>> b/clang/include/clang/Basic/AttrDocs.td
>> index f73fbd08e3bf..734cf026ae87 100644
>> --- a/clang/include/clang/Basic/AttrDocs.td
>> +++ b/clang/include/clang/Basic/AttrDocs.td
>> @@ -3032,10 +3032,39 @@ is retained by the return value of the annotated
>> function
>>  (or, for a parameter of a constructor, in the value of the constructed
>> object).
>>  It is only supported in C++.
>>
>> -This attribute provides an experimental implementation of the facility
>> -described in the C++ committee paper `P0936R0 > >`_,
>> -and is subject to change as the design of the corresponding functionality
>> -changes.
>> +This attribute causes warnings to be produced if a temporary object does
>> not
>> +live long enough. For example:
>> +
>> +.. code-block:: c++
>> +
>> +template
>> +const U _or_default(std::map , const T ,
>> +const U _value
>> [[clang::lifetimebound]]);
>> +
>> +std::map m;
>> +// warning: temporary "bar"s that might be bound to local reference
>> 'val'
>> +// will be destroyed at the end of the full-expression
>> +const std::string  = get_or_default(m, "foo"s, "bar"s);
>> +
>> +When applied to a reference parameter, the referenced object is assumed
>> to be
>> +retained by the return value of the function. When applied to a
>> non-reference
>> +parameter (for example, a pointer or a class type), all temporaries
>> referenced
>> +by the parameter are assumed to be retained by the return value of the
>> +function.
>>
>
> "referenced by" seems a bit vague to me - I guess it means all reference
> members of the parameter? (what about reference members of subobjects?)
>

I'll send you a further improvement to review :)


> +
>> +The attribute can be applied to the implicit ``this`` parameter of a
>> member
>> +function by writing the attribute after the function type:
>> +
>> +.. code-block:: c++
>> +
>> +struct string_view {
>> +  // ...
>> +  const char *data() const [[clang::lifetimebound]];
>> +};
>> +
>> +This attribute is inspired by the C++ committee paper `P0936R0
>> +`_, but does not affect whether temporary
>> objects
>> +have their lifetimes extended.
>>}];
>>  }
>>
>>
>>
>>
>> ___
>> cfe-commits mailing list
>> cfe-commits@lists.llvm.org
>> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
>>
>
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Re: [clang] 5c689e4 - Improve documentation for the [[clang::lifetimebound]] attribute.

2021-03-22 Thread David Blaikie via cfe-commits 
On Thu, Mar 18, 2021 at 7:58 PM Richard Smith via cfe-commits <
cfe-commits@lists.llvm.org> wrote:

>
> Author: Richard Smith
> Date: 2021-03-18T19:58:21-07:00
> New Revision: 5c689e4bb0473e08645547ddbf9874b5e2fa04d0
>
> URL:
> https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0
> DIFF:
> https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0.diff
>
> LOG: Improve documentation for the [[clang::lifetimebound]] attribute.
>
> Added:
>
>
> Modified:
> clang/include/clang/Basic/AttrDocs.td
>
> Removed:
>
>
>
>
> 
> diff  --git a/clang/include/clang/Basic/AttrDocs.td
> b/clang/include/clang/Basic/AttrDocs.td
> index f73fbd08e3bf..734cf026ae87 100644
> --- a/clang/include/clang/Basic/AttrDocs.td
> +++ b/clang/include/clang/Basic/AttrDocs.td
> @@ -3032,10 +3032,39 @@ is retained by the return value of the annotated
> function
>  (or, for a parameter of a constructor, in the value of the constructed
> object).
>  It is only supported in C++.
>
> -This attribute provides an experimental implementation of the facility
> -described in the C++ committee paper `P0936R0  >`_,
> -and is subject to change as the design of the corresponding functionality
> -changes.
> +This attribute causes warnings to be produced if a temporary object does
> not
> +live long enough. For example:
> +
> +.. code-block:: c++
> +
> +template
> +const U _or_default(std::map , const T ,
> +const U _value
> [[clang::lifetimebound]]);
> +
> +std::map m;
> +// warning: temporary "bar"s that might be bound to local reference
> 'val'
> +// will be destroyed at the end of the full-expression
> +const std::string  = get_or_default(m, "foo"s, "bar"s);
> +
> +When applied to a reference parameter, the referenced object is assumed
> to be
> +retained by the return value of the function. When applied to a
> non-reference
> +parameter (for example, a pointer or a class type), all temporaries
> referenced
> +by the parameter are assumed to be retained by the return value of the
> +function.
>

"referenced by" seems a bit vague to me - I guess it means all reference
members of the parameter? (what about reference members of subobjects?)


> +
> +The attribute can be applied to the implicit ``this`` parameter of a
> member
> +function by writing the attribute after the function type:
> +
> +.. code-block:: c++
> +
> +struct string_view {
> +  // ...
> +  const char *data() const [[clang::lifetimebound]];
> +};
> +
> +This attribute is inspired by the C++ committee paper `P0936R0
> +`_, but does not affect whether temporary
> objects
> +have their lifetimes extended.
>}];
>  }
>
>
>
>
> ___
> cfe-commits mailing list
> cfe-commits@lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
>
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] 5c689e4 - Improve documentation for the [[clang::lifetimebound]] attribute.

2021-03-18 Thread Richard Smith via cfe-commits 

Author: Richard Smith
Date: 2021-03-18T19:58:21-07:00
New Revision: 5c689e4bb0473e08645547ddbf9874b5e2fa04d0

URL: 
https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0
DIFF: 
https://github.com/llvm/llvm-project/commit/5c689e4bb0473e08645547ddbf9874b5e2fa04d0.diff

LOG: Improve documentation for the [[clang::lifetimebound]] attribute.

Added: 


Modified: 
clang/include/clang/Basic/AttrDocs.td

Removed: 




diff  --git a/clang/include/clang/Basic/AttrDocs.td 
b/clang/include/clang/Basic/AttrDocs.td
index f73fbd08e3bf..734cf026ae87 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -3032,10 +3032,39 @@ is retained by the return value of the annotated 
function
 (or, for a parameter of a constructor, in the value of the constructed object).
 It is only supported in C++.
 
-This attribute provides an experimental implementation of the facility
-described in the C++ committee paper `P0936R0 `_,
-and is subject to change as the design of the corresponding functionality
-changes.
+This attribute causes warnings to be produced if a temporary object does not
+live long enough. For example:
+
+.. code-block:: c++
+
+template
+const U _or_default(std::map , const T ,
+const U _value [[clang::lifetimebound]]);
+
+std::map m;
+// warning: temporary "bar"s that might be bound to local reference 'val'
+// will be destroyed at the end of the full-expression
+const std::string  = get_or_default(m, "foo"s, "bar"s);
+
+When applied to a reference parameter, the referenced object is assumed to be
+retained by the return value of the function. When applied to a non-reference
+parameter (for example, a pointer or a class type), all temporaries referenced
+by the parameter are assumed to be retained by the return value of the
+function.
+
+The attribute can be applied to the implicit ``this`` parameter of a member
+function by writing the attribute after the function type:
+
+.. code-block:: c++
+
+struct string_view {
+  // ...
+  const char *data() const [[clang::lifetimebound]];
+};
+
+This attribute is inspired by the C++ committee paper `P0936R0
+`_, but does not affect whether temporary objects
+have their lifetimes extended.
   }];
 }
 



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits