Add details about integer overflow

src/behavior-not-considered-unsafe.md

@@ -1,15 +1,38 @@
-## Behavior not considered unsafe
-
-This is a list of behavior not considered *unsafe* in Rust terms, but that may
-be undesired.
-
-* Deadlocks
-* Leaks of memory and other resources
-* Exiting without calling destructors
-* Integer overflow
-  - Overflow is considered "unexpected" behavior and is always user-error,
-    unless the `wrapping` primitives are used. In non-optimized builds, the compiler
-    will insert debug checks that panic on overflow, but in optimized builds overflow
-    instead results in wrapped values. See [RFC 560] for the rationale and more details.
+## Behavior not considered `unsafe`
+
+The Rust compiler does not consider the following behaviors _unsafe_,
+though a programmer may (should) find them undesirable, unexpected,
+or erroneous.
+
+##### Deadlocks
+##### Leaks of memory and other resources
+##### Exiting without calling destructors
+##### Integer overflow
+
+If a program contains arithmetic overflow, the programmer has made an
+error. In the following discussion, we maintain a distinction between
+arithmetic overflow and wrapping arithmetic. The first is erroneous,
+while the second is intentional.
+
+When the programmer has enabled `debug_assert!` assertions (for
+example, by enabling a non-optimized build), implementations must
+insert dynamic checks that `panic` on overflow. Other kinds of builds
+may result in `panics` or silently wrapped values on overflow, at the
+implementation's discretion.
+
+In the case of implicitly-wrapped overflow, implementations must
+provide well-defined (even if still considered erroneous) results by
+using two's complement overflow conventions.
+
+The integral types provide inherent methods to allow programmers
+explicitly to perform wrapping arithmetic. For example,
+`i32::wrapping_add` provides two's complement, wrapping addition.
+
+The standard library also provides a `Wrapping<T>` newtype which
+ensures all standard arithmetic operations for `T` have wrapping
+semantics.
+
+See [RFC 560] for error conditions, rationale, and more details about
+integer overflow.
 
 [RFC 560]: https://github.com/rust-lang/rfcs/blob/master/text/0560-integer-overflow.md

src/undocumented.md

@@ -16,8 +16,6 @@ to shrink!
   in [Conditional compilation]
 - [Unambiguous function call syntax]
 - [Require parentheses for chained comparisons]
-- [Integer overflow not `unsafe`] - documented with a reference to the RFC, but
-  requires further details
 - [`dllimport`] - one element mentioned but not explained at [FFI attributes]
 - [define `crt_link`]
 - [define `unaligned_access`]