Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve some pointer-related documentation #62822

Merged
merged 8 commits into from
Jul 26, 2019
12 changes: 7 additions & 5 deletions src/libstd/primitive_docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -363,10 +363,11 @@ mod prim_unit { }
/// *[See also the `std::ptr` module](ptr/index.html).*
///
/// Working with raw pointers in Rust is uncommon, typically limited to a few patterns.
/// Raw pointers can be unaligned or null when unused. However, when a raw pointer is used to
/// load/store data from/to memory, they must be non-null and aligned.
/// Storing through a raw pointer (`*ptr = data`) calls `drop` on the old value, so
/// [`write`] must be used if memory is not already initialized.
/// Raw pointers can be unaligned or [`null`] when unused. However, when a raw pointer is
RalfJung marked this conversation as resolved.
Show resolved Hide resolved
/// dereferenced (using the `*` operator), it must be non-null and aligned.
/// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so
/// [`write`] must be used if memory is not already initialized---otherwise `drop`
/// would be called on the uninitialized memory.
Centril marked this conversation as resolved.
Show resolved Hide resolved
///
/// Use the [`null`] and [`null_mut`] functions to create null pointers, and the
/// [`is_null`] method of the `*const T` and `*mut T` types to check for null.
Expand Down Expand Up @@ -896,7 +897,8 @@ mod prim_usize { }
/// operators on a value, or by using a `ref` or `ref mut` pattern.
///
/// For those familiar with pointers, a reference is just a pointer that is assumed to be
Centril marked this conversation as resolved.
Show resolved Hide resolved
/// aligned and not null. In fact, `Option<&T>` has the same memory representation as a
/// aligned, not null, and pointing to valid (initialized) memory.
RalfJung marked this conversation as resolved.
Show resolved Hide resolved
/// In fact, `Option<&T>` has the same memory representation as a
/// nullable but aligned pointer, and can be passed across FFI boundaries as such.
///
/// In most cases, references can be used much like the original value. Field access, method
Expand Down