From c82af09bb0fb78379cf3b525d22f902b3139217f Mon Sep 17 00:00:00 2001
From: Without Boats <boats@mozilla.com>
Date: Wed, 5 Sep 2018 23:47:10 +0200
Subject: [PATCH] Add comment.

---
 src/liballoc/boxed.rs | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index f16a112b801..aeed139ebb7 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -749,6 +749,28 @@ impl<T: ?Sized> AsMut<T> for Box<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> { }