Document return value of zero-size/zero-heap pointer types.

Fixes #39625.

Author: frewsxcv

src/liballoc/arc.rs

@@ -282,6 +282,9 @@ impl<T> Arc<T> {
     /// To avoid a memory leak the pointer must be converted back to an `Arc` using
     /// [`Arc::from_raw`][from_raw].
     ///
+    /// If `T` is zero-sized (e.g. `Arc<()>`), the returned pointer address
+    /// will be meaningless.
+    ///
     /// [from_raw]: struct.Arc.html#method.from_raw
     ///
     /// # Examples

src/liballoc/boxed.rs

@@ -274,6 +274,9 @@ impl<T: ?Sized> Box<T> {
     /// proper way to do so is to convert the raw pointer back into a
     /// `Box` with the [`Box::from_raw`] function.
     ///
+    /// If `T` is zero-sized (e.g. `Box<()>`), the returned pointer address
+    /// will be meaningless.
+    ///
     /// Note: this is an associated function, which means that you have
     /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This
     /// is so that there is no conflict with a method on the inner type.

src/liballoc/rc.rs

@@ -359,6 +359,9 @@ impl<T> Rc<T> {
     /// To avoid a memory leak the pointer must be converted back to an `Rc` using
     /// [`Rc::from_raw`][from_raw].
     ///
+    /// If `T` is zero-sized (e.g. `Rc<()>`), the returned pointer address
+    /// will be meaningless.
+    ///
     /// [from_raw]: struct.Rc.html#method.from_raw
     ///
     /// # Examples

src/libcollections/slice.rs

@@ -437,6 +437,9 @@ impl<T> [T] {
     /// The caller must ensure that the slice outlives the pointer this
     /// function returns, or else it will end up pointing to garbage.
     ///
+    /// If the slice is empty, the returned pointer address will be
+    /// meaningless.
+    ///
     /// Modifying the slice may cause its buffer to be reallocated, which
     /// would also make any pointers to it invalid.
     ///
@@ -463,6 +466,9 @@ impl<T> [T] {
     /// The caller must ensure that the slice outlives the pointer this
     /// function returns, or else it will end up pointing to garbage.
     ///
+    /// If the slice is empty, the returned pointer address will be
+    /// meaningless.
+    ///
     /// Modifying the slice may cause its buffer to be reallocated, which
     /// would also make any pointers to it invalid.
     ///

src/libcollections/str.rs

@@ -275,6 +275,9 @@ impl str {
     /// [`u8`]. This pointer will be pointing to the first byte of the string
     /// slice.
     ///
+    /// If the string slice is empty, the returned pointer address will be
+    /// meaningless.
+    ///
     /// [`u8`]: primitive.u8.html
     ///
     /// # Examples

src/libcore/cell.rs

@@ -235,6 +235,9 @@ impl<T:Copy> Cell<T> {
 
     /// Returns a raw pointer to the underlying data in this cell.
     ///
+    /// If `T` is zero-sized (e.g. `Cell<()>`), the returned pointer address
+    /// will be meaningless.
+    ///
     /// # Examples
     ///
     /// ```
@@ -771,6 +774,9 @@ impl<T: ?Sized> RefCell<T> {
 
     /// Returns a raw pointer to the underlying data in this cell.
     ///
+    /// If `T` is zero-sized (e.g. `RefCell<()>`), the returned pointer address
+    /// will be meaningless.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1188,6 +1194,9 @@ impl<T: ?Sized> UnsafeCell<T> {
     /// `&mut T`, and ensure that there are no mutations or mutable
     /// aliases going on when casting to `&T`
     ///
+    /// If `T` is zero-sized (e.g. `UnsafeCell<()>`), the returned pointer
+    /// address will be meaningless.
+    ///
     /// # Examples
     ///
     /// ```