From 709b7515e744cdf242ab53806414aa295ea6977f Mon Sep 17 00:00:00 2001
From: Taylor Cramer <cramertj@google.com>
Date: Thu, 15 Nov 2018 15:49:16 -0800
Subject: [PATCH] Rename Pinned marker type to PhantomPinned

---
 src/libcore/marker.rs |  8 ++++----
 src/libcore/pin.rs    | 11 +++++++----
 2 files changed, 11 insertions(+), 8 deletions(-)

diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs
index 0d43f927115f8..d3d16127ed5fe 100644
--- a/src/libcore/marker.rs
+++ b/src/libcore/marker.rs
@@ -640,15 +640,15 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
 #[unstable(feature = "pin", issue = "49150")]
 pub auto trait Unpin {}
 
-/// A type which does not implement `Unpin`.
+/// A marker type which does not implement `Unpin`.
 ///
-/// If a type contains a `Pinned`, it will not implement `Unpin` by default.
+/// If a type contains a `PhantomPinned`, it will not implement `Unpin` by default.
 #[unstable(feature = "pin", issue = "49150")]
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
-pub struct Pinned;
+pub struct PhantomPinned;
 
 #[unstable(feature = "pin", issue = "49150")]
-impl !Unpin for Pinned {}
+impl !Unpin for PhantomPinned {}
 
 #[unstable(feature = "pin", issue = "49150")]
 impl<'a, T: ?Sized + 'a> Unpin for &'a T {}
diff --git a/src/libcore/pin.rs b/src/libcore/pin.rs
index 256a1d60ac2e5..0ad6e8c7c1c7d 100644
--- a/src/libcore/pin.rs
+++ b/src/libcore/pin.rs
@@ -19,7 +19,10 @@
 //! Since data can be moved out of `&mut` and `Box` with functions such as [`swap`],
 //! changing the location of the underlying data, [`Pin`] prohibits accessing the
 //! underlying pointer type (the `&mut` or `Box`) directly, and provides its own set of
-//! APIs for accessing and using the value.
+//! APIs for accessing and using the value. [`Pin`] also guarantees that no other
+//! functions will move the pointed-to value. This allows for the creation of
+//! self-references and other special behaviors that are only possible for unmovable
+//! values.
 //!
 //! However, these restrictions are usually not necessary. Many types are always freely
 //! movable. These types implement the [`Unpin`] auto-trait, which nullifies the affect
@@ -43,7 +46,7 @@
 //! #![feature(pin)]
 //!
 //! use std::pin::Pin;
-//! use std::marker::Pinned;
+//! use std::marker::PhantomPinned;
 //! use std::ptr::NonNull;
 //!
 //! // This is a self-referential struct since the slice field points to the data field.
@@ -54,7 +57,7 @@
 //! struct Unmovable {
 //!     data: String,
 //!     slice: NonNull<String>,
-//!     _pin: Pinned,
+//!     _pin: PhantomPinned,
 //! }
 //!
 //! impl Unmovable {
@@ -67,7 +70,7 @@
 //!             // we only create the pointer once the data is in place
 //!             // otherwise it will have already moved before we even started
 //!             slice: NonNull::dangling(),
-//!             _pin: Pinned,
+//!             _pin: PhantomPinned,
 //!         };
 //!         let mut boxed = Box::pinned(res);
 //!