Extend documentation for Ty::to_opt_closure_kind method

compiler/rustc_middle/src/ty/sty.rs

@@ -2362,6 +2362,20 @@ pub fn ptr_metadata_ty(
     /// 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 {