Attempt to further improve the documentation for the [[clang::lifetimebound]] attribute.

[dblaikie]

clang/include/clang/Basic/AttrDocs.td

3038–3039

I take it this is the recursive definition that addresses my question? Sounds good to me. (could make that more explicit if you like, but I don't feel too strongly either way)

[rsmith]

clang/include/clang/Basic/AttrDocs.td

3038–3039

Yes, that's the intent. Thanks for the review!

clang/include/clang/Basic/AttrDocs.td

 This attribute only applies to struct, class, and union types.
 It is only supported when using the Microsoft C++ ABI.
   }];
 }
 
 def LifetimeBoundDocs : Documentation {
   let Category = DocCatFunction;
   let Content = [{
-The ``lifetimebound`` attribute indicates that a resource owned by
-a function parameter or implicit object parameter
-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 causes warnings to be produced if a temporary object does not
-live long enough. For example:
+The ``lifetimebound`` attribute on a function parameter or implicit object
+parameter indicates that objects that are referred to by that parameter may
+also be referred to by the return value of the annotated function (or, for a
+parameter of a constructor, by the value of the constructed object). It is only
+supported in C++.
+
+By default, a reference is considered to refer to its referenced object, a
+pointer is considered to refer to its pointee, a ``std::initializer_list<T>``
+is considered to refer to its underlying array, and aggregates (arrays and
+simple ``struct``s) are considered to refer to all objects that their
+subobjects refer to.
+
+Clang warns if it is able to detect that an object or reference refers to
+another object with a shorter lifetime. For example, Clang will warn if a
+function returns a reference to a local variable, or if a reference is bound to
+a temporary object whose lifetime is not extended. By using the
+``lifetimebound`` attribute, this determination can be extended to look through
+user-declared functions. For example:
 
 .. code-block:: c++
 
+    // Returns m[key] if key is present, or default_value if not.
     template<typename T, typename U>
-    const U &get_or_default(std::map<T, U> &m, const T &key,
+    const U &get_or_default(const std::map<T, U> &m [[clang::lifetimebound]],
+                            const T &key, /* note, not lifetimebound */
                             const U &default_value [[clang::lifetimebound]]);
 
     std::map<std::string, std::string> 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 &val = 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.
+    // No warning in this case.
+    std::string def_val = "bar"s;
+    const std::string &val = get_or_default(m, "foo"s, def_val);
 
 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 {
       // The returned pointer should not outlive ``*this``.