Rollup merge of #105902 - vincenzopalazzo:macros/pin_docs, r=eholk

docs: improve pin docs

Override #104195 with a full cleanup of the git history, now it should be ready to be merged.

r? `@eholk`

`@rustbot` label +A-async-await

Author: matthiaskrgr

library/core/src/pin.rs

@@ -485,6 +485,16 @@ impl<P: Deref<Target: Unpin>> Pin<P> {
     ///
     /// Unlike `Pin::new_unchecked`, this method is safe because the pointer
     /// `P` dereferences to an [`Unpin`] type, which cancels the pinning guarantees.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::pin::Pin;
+    ///
+    /// let mut val: u8 = 5;
+    /// // We can pin the value, since it doesn't care about being moved
+    /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
+    /// ```
     #[inline(always)]
     #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
     #[stable(feature = "pin", since = "1.33.0")]
@@ -496,8 +506,20 @@ impl<P: Deref<Target: Unpin>> Pin<P> {
 
     /// Unwraps this `Pin<P>` returning the underlying pointer.
     ///
-    /// This requires that the data inside this `Pin` is [`Unpin`] so that we
+    /// This requires that the data inside this `Pin` implements [`Unpin`] so that we
     /// can ignore the pinning invariants when unwrapping it.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::pin::Pin;
+    ///
+    /// let mut val: u8 = 5;
+    /// let pinned: Pin<&mut u8> = Pin::new(&mut val);
+    /// // Unwrap the pin to get a reference to the value
+    /// let r = Pin::into_inner(pinned);
+    /// assert_eq!(*r, 5);
+    /// ```
     #[inline(always)]
     #[rustc_const_unstable(feature = "const_pin", issue = "76654")]
     #[stable(feature = "pin_into_inner", since = "1.39.0")]
@@ -707,6 +729,18 @@ impl<P: DerefMut> Pin<P> {
     ///
     /// This overwrites pinned data, but that is okay: its destructor gets
     /// run before being overwritten, so no pinning guarantee is violated.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use std::pin::Pin;
+    ///
+    /// let mut val: u8 = 5;
+    /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val);
+    /// println!("{}", pinned); // 5
+    /// pinned.as_mut().set(10);
+    /// println!("{}", pinned); // 10
+    /// ```
     #[stable(feature = "pin", since = "1.33.0")]
     #[inline(always)]
     pub fn set(&mut self, value: P::Target)