doc: Clarify the lifetime returned by `Box::leak`

`Box::leak` mentions that it can return a `'static` reference, but it
wasn't immediately clear to me why it doesn't always do so.  This is
because of the `T: 'a` constraint needed to form a valid reference, and
in general we want to be more flexible than requiring `T: 'static`.
This patch tries to clarify the relationship between `T` and `'a`.

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index fb16bdf0ab43ae4d4872b87f4c44d5bb6aabb081..8a65843b50d7d5d55dd072991da094c0e28ac2b3 100644 (file)
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -194,7 +194,9 @@ pub fn into_unique(b: Box<T>) -> Unique<T> {
     }
 
     /// Consumes and leaks the `Box`, returning a mutable reference,
-    /// `&'a mut T`. Here, the lifetime `'a` may be chosen to be `'static`.
+    /// `&'a mut T`. Note that the type `T` must outlive the chosen lifetime
+    /// `'a`. If the type has only static references, or none at all, then this
+    /// may be chosen to be `'static`.
     ///
     /// This function is mainly useful for data that lives for the remainder of
     /// the program's life. Dropping the returned reference will cause a memory