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

[Erich Keane via llvm-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:

Right, I'm just suggesting we give 'motivating' text for folks to read, not "this pass does X, this pass does Y". In this case, if I were to see "better optimizations" that doesn't help/isn't particularly actionable.  But if I see, "Allows for better code size in cases where a coroutine is known to ONLY be destroyed after its final suspend point", and I have one of those, it might be 'relevant to my interests!'.

While the example was good, I found I wasn't able to determine WHAT the attribute was doing until investing a lot of time reading, we want our users/doc readers to be 'hooked' on being interest (or, alternatively, be able to tell they don't need to continue reading) as soon as possible.  Does that make sense?

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