Rollup merge of #116129 - fu5ha:better-pin-docs-2, r=Amanieu

Rewrite `pin` module documentation to clarify usage and invariants

The documentation of `pin` today does not give a complete treatment of pinning from first principles, nor does it adequately help build intuition and understanding for how the different elements of the pinning story fit together.

This rewrite attempts to address these in a way that makes the concept more approachable while also making the documentation more normative.

This PR picks up where `@mcy` left off in #88500 (thanks to him for the original work and `@Manishearth` for mentioning it such that I originally found it). I've directly incorporated much of the feedback left on the original PR and have rewritten and changed some of the main conceits of the prose to better adhere to the feedback from the reviewers on that PR or just explain something in (hopefully) a better way.

4 files changed, 5 insertions, 5 deletions

diff --git a/tests/ui/async-await/pin-needed-to-poll-2.stderr b/tests/ui/async-await/pin-needed-to-poll-2.stderr
index 9c1ad32cc2c..8eb671531e7 100644
--- a/tests/ui/async-await/pin-needed-to-poll-2.stderr
+++ b/tests/ui/async-await/pin-needed-to-poll-2.stderr
@@ -13,7 +13,7 @@ note: required because it appears within the type `Sleep`
    |
 LL | struct Sleep(std::marker::PhantomPinned);
    |        ^^^^^
-note: required by a bound in `Pin::<P>::new`
+note: required by a bound in `Pin::<Ptr>::new`
   --> $SRC_DIR/core/src/pin.rs:LL:COL
 
 error: aborting due to 1 previous error
diff --git a/tests/ui/closures/coerce-unsafe-closure-to-unsafe-fn-ptr.stderr b/tests/ui/closures/coerce-unsafe-closure-to-unsafe-fn-ptr.stderr
index f5cb3e2b5f8..48fc8461882 100644
--- a/tests/ui/closures/coerce-unsafe-closure-to-unsafe-fn-ptr.stderr
+++ b/tests/ui/closures/coerce-unsafe-closure-to-unsafe-fn-ptr.stderr
@@ -1,4 +1,4 @@
-error[E0133]: call to unsafe function `Pin::<P>::new_unchecked` is unsafe and requires unsafe function or block
+error[E0133]: call to unsafe function `Pin::<Ptr>::new_unchecked` is unsafe and requires unsafe function or block
   --> $DIR/coerce-unsafe-closure-to-unsafe-fn-ptr.rs:2:31
    |
 LL |     let _: unsafe fn() = || { ::std::pin::Pin::new_unchecked(&0_u8); };
diff --git a/tests/ui/self/arbitrary_self_types_pin_needing_borrow.stderr b/tests/ui/self/arbitrary_self_types_pin_needing_borrow.stderr
index ec985b254b3..1811cd6753f 100644
--- a/tests/ui/self/arbitrary_self_types_pin_needing_borrow.stderr
+++ b/tests/ui/self/arbitrary_self_types_pin_needing_borrow.stderr
@@ -6,7 +6,7 @@ LL |     Pin::new(S).x();
    |     |
    |     required by a bound introduced by this call
    |
-note: required by a bound in `Pin::<P>::new`
+note: required by a bound in `Pin::<Ptr>::new`
   --> $SRC_DIR/core/src/pin.rs:LL:COL
 help: consider borrowing here
    |
diff --git a/tests/ui/suggestions/expected-boxed-future-isnt-pinned.stderr b/tests/ui/suggestions/expected-boxed-future-isnt-pinned.stderr
index 7c81825e576..60ab392f55d 100644
--- a/tests/ui/suggestions/expected-boxed-future-isnt-pinned.stderr
+++ b/tests/ui/suggestions/expected-boxed-future-isnt-pinned.stderr
@@ -52,7 +52,7 @@ LL |     Pin::new(x)
    |
    = note: consider using the `pin!` macro
            consider using `Box::pin` if you need to access the pinned value outside of the current scope
-note: required by a bound in `Pin::<P>::new`
+note: required by a bound in `Pin::<Ptr>::new`
   --> $SRC_DIR/core/src/pin.rs:LL:COL
 
 error[E0277]: `dyn Future<Output = i32> + Send` cannot be unpinned
@@ -65,7 +65,7 @@ LL |     Pin::new(Box::new(x))
    |
    = note: consider using the `pin!` macro
            consider using `Box::pin` if you need to access the pinned value outside of the current scope
-note: required by a bound in `Pin::<P>::new`
+note: required by a bound in `Pin::<Ptr>::new`
   --> $SRC_DIR/core/src/pin.rs:LL:COL
 
 error[E0308]: mismatched types