[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:

Please clarify what benefits here, just an ominous 'better optimizations' isn't as helpful as a description of the type of optimizations (in laymans terms) we can provide.  The example helps, but a better 'intro summary' would be greatly appreciated.

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