Box::into_raw doesn't document that the returned pointer will not be null

[jonas-schievink]

The existence of the unstable Box::into_raw_non_null kind of hints that this is the case (as does an understanding of how Box internally works), but it would be nice for unsafe code to actually guarantee this.

[estk]

@kennytm and @jonas-schievink I started looking into this and I'd be happy to update the docs. After having a look over the code however I was a bit confused about how if at all the docs could be improved.

This line:

rust/src/liballoc/boxed.rs

Line 155 in ccb550f

/// Consumes the `Box`, returning the wrapped pointer as `NonNull<T>`.

To me, it seems sufficient to indicate that the pointer will not be null, @jonas-schievink how do you think it should be improved?

[sfackler]

Box always points to a valid allocation, and null is not a valid allocation.

[jonas-schievink]

@estk That line is for into_raw_non_null, not into_raw. For the latter, just an additional sentence stating that the returned pointer is guaranteed to not be null should be enough - maybe adding that the pointer will be properly aligned is a good idea, too.