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`.

1 files changed, 3 insertions, 1 deletions

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index fb16bdf0ab4..8a65843b50d 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -194,7 +194,9 @@ impl<T: ?Sized> Box<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