Rollup merge of #121083 - GuillaumeGomez:doc-to_opt_closure_kind, r=compiler-errors

Extend documentation for `Ty::to_opt_closure_kind` method

This API was... surprising to use. With a little extra documentation, the weirdness can be reduced quite a lot. :)

r? `@compiler-errors`

compiler/rustc_middle/src/ty/sty.rs

@@ -2373,6 +2373,20 @@ impl<'tcx> Ty<'tcx> {
     /// to represent the closure kind, because it has not yet been
     /// inferred. Once upvar inference (in `rustc_hir_analysis/src/check/upvar.rs`)
     /// is complete, that type variable will be unified.
+    ///
+    /// To be noted that you can use [`ClosureArgs::kind()`] or [`CoroutineClosureArgs::kind()`]
+    /// to get the same information, which you can get by calling [`GenericArgs::as_closure()`]
+    /// or [`GenericArgs::as_coroutine_closure()`], depending on the type of the closure.
+    ///
+    /// Otherwise, this method can be used as follows:
+    ///
+    /// ```rust,ignore (snippet of compiler code)
+    /// let TyKind::Closure(def_id, [closure_fn_kind_ty, ..]) = closure_ty.kind()
+    ///     && let Some(closure_kind) = closure_fn_kind_ty.expect_ty().to_opt_closure_kind()
+    /// {
+    ///     // your code
+    /// }
+    /// ```
     pub fn to_opt_closure_kind(self) -> Option<ty::ClosureKind> {
         match self.kind() {
             Int(int_ty) => match int_ty {