Add examples in stdlib demonstrating the use syntax

Author: spastorino

library/core/src/marker.rs

@@ -465,6 +465,25 @@ impl<T: ?Sized> Copy for &T {}
 ///
 /// The `UseCloned` trait does not provide a method; instead, it indicates that
 /// `Clone::clone` is lightweight, and allows the use of the `.use` syntax.
+///
+/// ## .use postfix syntax
+///
+/// Values can be `.use`d by adding `.use` postfix to the value you want to use.
+///
+/// ```
+/// fn foo(f: Foo) {
+///     // if `Foo` implements `Copy` f would be copied into x.
+///     // if `Foo` implements `UseCloned` f would be cloned into x.
+///     // otherwise f would be moved into x.
+///     let x = f.use;
+///     // ...
+/// }
+/// ```
+///
+/// ## use closures
+///
+/// Use closures allow captured values to be automatically used.
+/// This is similar to have a closure that you would call `.use` over each captured value.
 #[unstable(feature = "ergonomic_clones", issue = "132290")]
 #[cfg_attr(not(bootstrap), lang = "use_cloned")]
 #[marker]

library/std/src/keyword_docs.rs

@@ -2370,6 +2370,12 @@ mod where_keyword {}
 /// [reference]: ../reference/expressions/loop-expr.html#predicate-loops
 mod while_keyword {}
 
+#[doc(keyword = "use")]
+//
+/// Use a values, copying its content if the value implements `Copy`, cloning the contents if the
+/// value implements `UseCloned` or moving it otherwise.
+mod use_keyword {}
+
 // 2018 Edition keywords
 
 #[doc(alias = "promise")]