avoid talking about inverses

library/core/src/ptr/const_ptr.rs

@@ -607,8 +607,9 @@ pub fn mask(self, mask: usize) -> *const T {
     /// Calculates the distance between two pointers. The returned value is in
     /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
     ///
-    /// This function is the inverse of [`offset`]: it is valid to call and will return
-    /// `n` if and only if `origin.offset(n)` is valid to call and will return `self`.
+    /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
+    /// except that it has a lot more opportunities for UB, in exchange for the compiler
+    /// better understanding what you are doing.
     ///
     /// [`offset`]: #method.offset
     ///
@@ -617,7 +618,7 @@ pub fn mask(self, mask: usize) -> *const T {
     /// If any of the following conditions are violated, the result is Undefined
     /// Behavior:
     ///
-    /// * Both the starting and other pointer must be either in bounds or one
+    /// * Both `self` and `origin` must be either in bounds or one
     ///   byte past the end of the same [allocated object].
     ///
     /// * Both pointers must be *derived from* a pointer to the same object.
@@ -651,8 +652,9 @@ pub fn mask(self, mask: usize) -> *const T {
     /// needed for `const`-compatibility: the distance between pointers into *different* allocated
     /// objects is not known at compile-time. However, the requirement also exists at
     /// runtime and may be exploited by optimizations. If you wish to compute the difference between
-    /// pointers that are not guaranteed to be from the same allocation, use `(self as
-    /// usize).sub(origin as usize) / mem::size_of::<T>()`.
+    /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
+    /// origin as isize) / mem::size_of::<T>()`.
+    // FIXME: recommend `addr()` instead of `as usize` once that is stable.
     ///
     /// [`add`]: #method.add
     /// [allocated object]: crate::ptr#allocated-object

library/core/src/ptr/mut_ptr.rs

@@ -781,8 +781,9 @@ pub const fn guaranteed_ne(self, other: *mut T) -> Option<bool>
     /// Calculates the distance between two pointers. The returned value is in
     /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
     ///
-    /// This function is the inverse of [`offset`]: it is valid to call and will return
-    /// `n` if and only if `origin.offset(n)` is valid to call and will return `self`.
+    /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
+    /// except that it has a lot more opportunities for UB, in exchange for the compiler
+    /// better understanding what you are doing.
     ///
     /// [`offset`]: pointer#method.offset-1
     ///
@@ -791,7 +792,7 @@ pub const fn guaranteed_ne(self, other: *mut T) -> Option<bool>
     /// If any of the following conditions are violated, the result is Undefined
     /// Behavior:
     ///
-    /// * Both the starting and other pointer must be either in bounds or one
+    /// * Both `self` and `origin` must be either in bounds or one
     ///   byte past the end of the same [allocated object].
     ///
     /// * Both pointers must be *derived from* a pointer to the same object.
@@ -825,8 +826,9 @@ pub const fn guaranteed_ne(self, other: *mut T) -> Option<bool>
     /// needed for `const`-compatibility: the distance between pointers into *different* allocated
     /// objects is not known at compile-time. However, the requirement also exists at
     /// runtime and may be exploited by optimizations. If you wish to compute the difference between
-    /// pointers that are not guaranteed to be from the same allocation, use `(self as
-    /// usize).sub(origin as usize) / mem::size_of::<T>()`.
+    /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
+    /// origin as isize) / mem::size_of::<T>()`.
+    // FIXME: recommend `addr()` instead of `as usize` once that is stable.
     ///
     /// [`add`]: #method.add
     /// [allocated object]: crate::ptr#allocated-object