expand the documentation on the Unpin trait

src/libcore/marker.rs

@@ -603,15 +603,22 @@ unsafe impl<T: ?Sized> Freeze for *mut T {}
 unsafe impl<'a, T: ?Sized> Freeze for &'a T {}
 unsafe impl<'a, T: ?Sized> Freeze for &'a mut T {}
 
-/// Types which can be moved out of a `PinMut`.
+/// Types which can be safely moved after being pinned.
 ///
-/// The `Unpin` trait is used to control the behavior of the [`PinMut`] type. If a
-/// type implements `Unpin`, it is safe to move a value of that type out of the
-/// `PinMut` pointer.
+/// Since Rust itself has no notion of immovable types, and will consider moves to always be safe,
+/// this trait cannot prevent types from moving by itself.
+///
+/// Instead it can be used to prevent moves through the type system,
+/// by controlling the behavior of special pointers types like [`PinMut`],
+/// which "pin" the type in place by wrapping it in a type which can only be dereferenced immutably.
+///
+/// Implementing this trait lifts the restrictions of pinning off a type,
+/// which then allows it to move out of said pointers with functions such as [`swap`].
 ///
 /// This trait is automatically implemented for almost every type.
 ///
 /// [`PinMut`]: ../mem/struct.PinMut.html
+/// [`swap`]: ../mem/fn.swap.html
 #[unstable(feature = "pin", issue = "49150")]
 pub auto trait Unpin {}