Correct docs for Address::unchecked_* methods.

The "unchecked" arithmatic methods on the Address trait were documented
to cause undefined behavior in the case of overflow or underflow. This
is a strange claim; if that were truly the case, the methods should have
been unsafe. It wasn't, though; every existing implementation of the
trait used the impl_address_ops! macro, which just implements them with
the standard Rust arithmatic operators, which follow this well-defined
behavior:
 - In debug mode, overflow is checked for and results in a panic.
 - In release mode, overflow results in silent wrapping.

The wrapping behavior may be surprising or result in incorrect behavior,
but it isn't undefined - we know exactly what will happen, and the
optimizer is required to preserve that - so we shouldn't call it
undefined.

It's also worth nothing that the names of these methods are a little
confusing - the integer types in std have unchecked_* methods that
actually invoke UB on overflow (and, accordingly, are unsafe). It might
be worth renaming these methods to something more consistent with std's
naming. This is slightly complicated by the fact that std doesn't
actually have a name for this behavior; it's just what the unqualified +
operator or .add() method does. We may not want that, though, if we're
trying to be more careful about overflow.

In any case, we don't have to know how it should work to document the
current behavior.

Signed-off-by: Gaelan Steele <[email protected]>

Author: Gaelan

src/address.rs

@@ -90,7 +90,11 @@ pub trait Address:
 
     /// Computes the offset from this address to the given base address.
     ///
-    /// Results in undefined behavior when an underflow occurs.
+    /// In the event of overflow, follows standard Rust behavior, i.e. panic in debug builds,
+    /// silently wrap in release builds.
+    ///
+    /// Note that, unlike the `unchecked_*` methods in std, this method never invokes undefined
+    /// behavior.
     /// # Examples
     ///
     /// ```
@@ -131,7 +135,11 @@ pub trait Address:
 
     /// Computes `self + offset`.
     ///
-    /// Results in undefined behavior when an overflow occurs.
+    /// In the event of overflow, follows standard Rust behavior, i.e. panic in debug builds,
+    /// silently wrap in release builds.
+    ///
+    /// Note that, unlike the `unchecked_*` methods in std, this method never invokes undefined
+    /// behavior..
     fn unchecked_add(&self, offset: Self::V) -> Self;
 
     /// Subtracts two addresses, checking for underflow. If underflow happens, `None` is returned.
@@ -146,7 +154,11 @@ pub trait Address:
 
     /// Computes `self - other`.
     ///
-    /// Results in undefined behavior when an underflow occurs.
+    /// In the event of underflow, follows standard Rust behavior, i.e. panic in debug builds,
+    /// silently wrap in release builds.
+    ///
+    /// Note that, unlike the `unchecked_*` methods in std, this method never invokes undefined
+    /// behavior.
     fn unchecked_sub(&self, other: Self::V) -> Self;
 }