@@ -3921,17 +3921,42 @@ have their lifetimes extended.
39213921def LifetimeCaptureByDocs : Documentation {
39223922 let Category = DocCatFunction;
39233923 let Content = [{
3924- Similar to `lifetimebound`_, the ``lifetime_capture_by(X)`` attribute on a function
3925- parameter or implicit object parameter indicates that that objects that are referred to
3926- by that parameter may also be referred to by the capturing entity ``X``.
3924+ Similar to `lifetimebound`_, the ``lifetime_capture_by(X)`` attribute on a
3925+ function parameter or implicit object parameter indicates that the capturing
3926+ entity ``X`` may refer to the object referred by that parameter.
3927+
3928+ Below is a list of types of the parameters and what they're considered to refer to:
3929+
3930+ - A reference param (of non-view type) is considered to refer to its referenced object.
3931+ - A pointer param (of non-view type) is considered to refer to its pointee.
3932+ - View type param (type annotated with ``[[gsl::Pointer()]]``) is considered to refer
3933+ to its pointee (gsl owner). This holds true even if the view type appears as a reference
3934+ in the parameter. For example, both ``std::string_view`` and
3935+ ``const std::string_view &`` are considered to refer to a ``std::string``.
3936+ - A ``std::initializer_list<T>`` is considered to refer to its underlying array.
3937+ - Aggregates (arrays and simple ``struct``\s) are considered to refer to all
3938+ objects that their transitive subobjects refer to.
3939+
3940+ Clang would diagnose when a temporary object is used as an argument to such an
3941+ annotated parameter.
3942+ In this case, the capturing entity ``X`` could capture a dangling reference to this
3943+ temporary object.
39273944
3928- By default, a reference is considered to refer to its referenced object, a
3929- pointer is considered to refer to its pointee, a ``std::initializer_list<T>``
3930- is considered to refer to its underlying array, and aggregates (arrays and
3931- simple ``struct``\s) are considered to refer to all objects that their
3932- transitive subobjects refer to.
3945+ .. code-block:: c++
3946+
3947+ void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
3948+ s.insert(a);
3949+ }
3950+ void use() {
3951+ std::set<std::string_view> s;
3952+ addToSet(std::string(), s); // Warning: object whose reference is captured by 's' will be destroyed at the end of the full-expression.
3953+ // ^^^^^^^^^^^^^
3954+ std::string local;
3955+ addToSet(local, s); // Ok.
3956+ }
39333957
39343958The capturing entity ``X`` can be one of the following:
3959+
39353960- Another (named) function parameter.
39363961
39373962 .. code-block:: c++
@@ -3951,7 +3976,7 @@ The capturing entity ``X`` can be one of the following:
39513976 std::set<std::string_view> s;
39523977 };
39533978
3954- - ' global', ' unknown' (without quotes) .
3979+ - ` global`, ` unknown` .
39553980
39563981 .. code-block:: c++
39573982
@@ -3983,6 +4008,22 @@ The attribute supports specifying more than one capturing entities:
39834008 s2.insert(a);
39844009 }
39854010
4011+ Limitation: The capturing entity ``X`` is not used by the analysis and is
4012+ used for documentation purposes only. This is because the analysis is
4013+ statement-local and only detects use of a temporary as an argument to the
4014+ annotated parameter.
4015+
4016+ .. code-block:: c++
4017+
4018+ void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s);
4019+ void use() {
4020+ std::set<std::string_view> s;
4021+ if (foo()) {
4022+ std::string str;
4023+ addToSet(str, s); // Not detected.
4024+ }
4025+ }
4026+
39864027.. _`lifetimebound`: https://clang.llvm.org/docs/AttributeReference.html#lifetimebound
39874028 }];
39884029}
@@ -8719,6 +8760,18 @@ Attribute used by `clspv`_ (OpenCL-C to Vulkan SPIR-V compiler) to identify func
87198760}];
87208761}
87218762
8763+ def NoTrivialAutoVarInitDocs : Documentation {
8764+ let Category = DocCatDecl;
8765+ let Content = [{
8766+ The ``__declspec(no_init_all)`` attribute disables the automatic initialization that the
8767+ `-ftrivial-auto-var-init`_ flag would have applied to locals in a marked function, or instances of
8768+ a marked type. Note that this attribute has no effect for locals that are automatically initialized
8769+ without the `-ftrivial-auto-var-init`_ flag.
8770+
8771+ .. _`-ftrivial-auto-var-init`: ClangCommandLineReference.html#cmdoption-clang-ftrivial-auto-var-init
8772+ }];
8773+ }
8774+
87228775def DocCatNonBlockingNonAllocating : DocumentationCategory<"Performance Constraint Attributes"> {
87238776 let Content = [{
87248777The ``nonblocking``, ``blocking``, ``nonallocating`` and ``allocating`` attributes can be attached
0 commit comments