From d411dd27bf391ca8da15a43341ad519a741b2e2a Mon Sep 17 00:00:00 2001 From: CreepySkeleton Date: Wed, 13 Nov 2019 20:43:45 +0300 Subject: [PATCH 1/2] Elaborate on std::ptr::{as_ref,as_mod} and clarify docs --- src/libcore/ptr/mod.rs | 38 ++++++++++++++++++++++++-------------- 1 file changed, 24 insertions(+), 14 deletions(-) diff --git a/src/libcore/ptr/mod.rs b/src/libcore/ptr/mod.rs index 39d56958f5d..21314d429c6 100644 --- a/src/libcore/ptr/mod.rs +++ b/src/libcore/ptr/mod.rs @@ -1074,17 +1074,22 @@ impl *const T { /// operation because the returned value could be pointing to invalid /// memory. /// - /// When calling this method, you have to ensure that if the pointer is - /// non-NULL, then it is properly aligned, dereferencable (for the whole - /// size of `T`) and points to an initialized instance of `T`. This applies - /// even if the result of this method is unused! + /// When calling this method, you have to ensure that *either* the pointer is NULL *or* + /// all of the following is true: + /// - it is properly aligned + /// - it must point to an initialized instance of T; in particular, the pointer must be + /// "dereferencable" in the sense defined [here]. + /// + /// This applies even if the result of this method is unused! /// (The part about being initialized is not yet fully decided, but until /// it is, the only safe approach is to ensure that they are indeed initialized.) /// /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does - /// not necessarily reflect the actual lifetime of the data. It is up to the - /// caller to ensure that for the duration of this lifetime, the memory this - /// pointer points to does not get written to outside of `UnsafeCell`. + /// not necessarily reflect the actual lifetime of the data. *You* must enforce + /// Rust's aliasing rules. In particular, for the duration of this lifetime, + /// the memory the pointer points to must not get mutated (except inside `UnsafeCell`). + /// + /// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety /// /// # Examples /// @@ -1929,18 +1934,23 @@ impl *mut T { /// of the returned pointer, nor can it ensure that the lifetime `'a` /// returned is indeed a valid lifetime for the contained data. /// - /// When calling this method, you have to ensure that if the pointer is - /// non-NULL, then it is properly aligned, dereferencable (for the whole - /// size of `T`) and points to an initialized instance of `T`. This applies - /// even if the result of this method is unused! + /// When calling this method, you have to ensure that *either* the pointer is NULL *or* + /// all of the following is true: + /// - it is properly aligned + /// - it must point to an initialized instance of T; in particular, the pointer must be + /// "dereferencable" in the sense defined [here]. + /// + /// This applies even if the result of this method is unused! /// (The part about being initialized is not yet fully decided, but until /// it is the only safe approach is to ensure that they are indeed initialized.) /// /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does - /// not necessarily reflect the actual lifetime of the data. It is up to the - /// caller to ensure that for the duration of this lifetime, the memory this - /// pointer points to does not get accessed through any other pointer. + /// not necessarily reflect the actual lifetime of the data. *You* must enforce + /// Rust's aliasing rules. In particular, for the duration of this lifetime, + /// the memory this pointer points to must not get accessed (read or written) + /// through any other pointer. /// + /// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety /// [`as_ref`]: #method.as_ref /// /// # Examples From f11dd32f751b4a64bea0bdd0020879caec197d3f Mon Sep 17 00:00:00 2001 From: CreepySkeleton Date: Wed, 27 Nov 2019 21:36:09 +0300 Subject: [PATCH 2/2] Use intra-doc links --- src/libcore/ptr/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcore/ptr/mod.rs b/src/libcore/ptr/mod.rs index 21314d429c6..1e051dbebca 100644 --- a/src/libcore/ptr/mod.rs +++ b/src/libcore/ptr/mod.rs @@ -1089,7 +1089,7 @@ impl *const T { /// Rust's aliasing rules. In particular, for the duration of this lifetime, /// the memory the pointer points to must not get mutated (except inside `UnsafeCell`). /// - /// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety + /// [here]: crate::ptr#safety /// /// # Examples /// @@ -1950,7 +1950,7 @@ impl *mut T { /// the memory this pointer points to must not get accessed (read or written) /// through any other pointer. /// - /// [here]: https://doc.rust-lang.org/std/ptr/index.html#safety + /// [here]: crate::ptr#safety /// [`as_ref`]: #method.as_ref /// /// # Examples