From 93a72daf8add8b4d8e56df9e41951c323dab750e Mon Sep 17 00:00:00 2001
From: Ralf Jung <post@ralfj.de>
Date: Thu, 29 Aug 2024 08:55:37 +0200
Subject: [PATCH] f32 docs: define 'arithmetic' operations

---
 core/src/primitive_docs.rs | 35 +++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/core/src/primitive_docs.rs b/core/src/primitive_docs.rs
index fe6ed7e0cf368..5003b5b482e2b 100644
--- a/core/src/primitive_docs.rs
+++ b/core/src/primitive_docs.rs
@@ -1219,22 +1219,25 @@ mod prim_f16 {}
 ///
 /// # NaN bit patterns
 ///
-/// This section defines the possible NaN bit patterns returned by non-"bitwise" floating point
-/// operations. The bitwise operations are unary `-`, `abs`, `copysign`; those are guaranteed to
-/// exactly preserve the bit pattern of their input except for possibly changing the sign bit.
+/// This section defines the possible NaN bit patterns returned by floating point operations.
 ///
-/// A floating-point NaN value consists of:
-/// - a sign bit
-/// - a quiet/signaling bit
+/// The bit pattern of a floating point NaN value is defined by:
+/// - a sign bit.
+/// - a quiet/signaling bit. Rust assumes that the quiet/signaling bit being set to `1` indicates a
+///   quiet NaN (QNaN), and a value of `0` indicates a signaling NaN (SNaN). In the following we
+///   will hence just call it the "quiet bit".
 /// - a payload, which makes up the rest of the significand (i.e., the mantissa) except for the
-///   quiet/signaling bit.
+///   quiet bit.
 ///
-/// Rust assumes that the quiet/signaling bit being set to `1` indicates a quiet NaN (QNaN), and a
-/// value of `0` indicates a signaling NaN (SNaN). In the following we will hence just call it the
-/// "quiet bit".
+/// The rules for NaN values differ between *arithmetic* and *non-arithmetic* (or "bitwise")
+/// operations. The non-arithmetic operations are unary `-`, `abs`, `copysign`, `signum`,
+/// `{to,from}_bits`, `{to,from}_{be,le,ne}_bytes` and `is_sign_{positive,negative}`. These
+/// operations are guaranteed to exactly preserve the bit pattern of their input except for possibly
+/// changing the sign bit.
 ///
-/// The following rules apply when a NaN value is returned: the result has a non-deterministic sign.
-/// The quiet bit and payload are non-deterministically chosen from the following set of options:
+/// The following rules apply when a NaN value is returned from an arithmetic operation: the result
+/// has a non-deterministic sign. The quiet bit and payload are non-deterministically chosen from
+/// the following set of options:
 ///
 /// - **Preferred NaN**: The quiet bit is set and the payload is all-zero.
 /// - **Quieting NaN propagation**: The quiet bit is set and the payload is copied from any input
@@ -1273,10 +1276,10 @@ mod prim_f16 {}
 /// (e.g. `min`, `minimum`, `max`, `maximum`); other aspects of their semantics and which IEEE 754
 /// operation they correspond to are documented with the respective functions.
 ///
-/// When a floating-point operation is executed in `const` context, the same rules apply: no
-/// guarantee is made about which of the NaN bit patterns described above will be returned. The
-/// result does not have to match what happens when executing the same code at runtime, and the
-/// result can vary depending on factors such as compiler version and flags.
+/// When an arithmetic floating point operation is executed in `const` context, the same rules
+/// apply: no guarantee is made about which of the NaN bit patterns described above will be
+/// returned. The result does not have to match what happens when executing the same code at
+/// runtime, and the result can vary depending on factors such as compiler version and flags.
 ///
 /// ### Target-specific "extra" NaN values
 // FIXME: Is there a better place to put this?