[clang] [llvm] [Coroutines] Introduce [[clang::coro_only_destroy_when_complete]] (PR #71014)

[Erich Keane via cfe-commits]

================
@@ -7416,3 +7416,69 @@ that ``p->array`` must have at least ``p->count`` number of elements available:
 
   }];
 }
+
+def CoroOnlyDestroyWhenCompleteDocs : Documentation {
+  let Category = DocCatDecl;
+  let Content = [{
+The `coro_only_destroy_when_complete` attribute should be marked on a C++ class. The coroutines
+whose return type is marked as the attribute are assumed to be destroyed only after then coroutines
+reached to the final suspend point.
+
+This is helpful for the optimizers to perform more optimizations.
----------------
erichkeane wrote:

Its better enough to be an 'intro' sentence at least.  And yes, our other documentation is bad, but we're trying to improve it.

Those are at least better 'understood' (or at least, understood in their lack of understanding) attributes that most folks can reason about, since they are documented plenty elsewhere (blogs, standards, etc).

https://github.com/llvm/llvm-project/pull/71014