Add comment.

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index f16a112b80119bb7bfa12efc26e67601a13dee8a..aeed139ebb76027dc5b0d08fa81fb5897dbab6c6 100644 (file)
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -749,6 +749,28 @@ fn as_mut(&mut self) -> &mut T {
     }
 }
 
+/* Nota bene
+ *
+ *  We could have chosen not to add this impl, and instead have written a 
+ *  function of Pin<Box<T>> to Pin<T>. Such a function would not be sound,
+ *  because Box<T> implements Unpin even when T does not, as a result of
+ *  this impl.
+ *
+ *  We chose this API instead of the alternative for a few reasons:
+ *      - Logically, it is helpful to understand pinning in regard to the
+ *        memory region being pointed to. For this reason none of the
+ *        standard library pointer types support projecting through a pin
+ *        (Box<T> is the only pointer type in std for which this would be
+ *        safe.)
+ *      - It is in practive very useful to have Box<T> be unconditionally
+ *        Unpin because of trait objects, for which the structural auto
+ *        trait functionality does not apply (e.g. Box<dyn Foo> would
+ *        otherwise not be Unpin).
+ *
+ *  Another type with the same semantics as Box but only a conditional
+ *  implementation of `Unpin` (where `T: Unpin`) would be valid/safe, and
+ *  could have a method to project a Pin<T> from it.
+ */
 #[unstable(feature = "pin", issue = "49150")]
 impl<T: ?Sized> Unpin for Box<T> { }