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

[Chuanqi Xu 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.
----------------
ChuanqiXu9 wrote:

Oh, I am not saying other documentation is bad. I mean, from the perspective of optimizers, it will never be able (or better not to) explain what the optimizations made by [[likey]], [[unlikely]] and [[assume]]. Since the optimizers want the freedom to perform any optimization they want as long as they doesn't violate the semantics. Otherwise, it'll be the responsibility of optimizers to report what they did after they made some non-trivial changes. It is generally not wanted by optimizers. We wish the programmers and implementers can focus more on semantics.

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