copysign with sign being a NaN is non-portable

4 files changed, 32 insertions, 12 deletions

diff --git a/library/std/src/f128.rs b/library/std/src/f128.rs
index 506d708d0d2..b436fe9929c 100644
--- a/library/std/src/f128.rs
+++ b/library/std/src/f128.rs
@@ -250,9 +250,14 @@ impl f128 {
     ///
     /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise equal to `-self`.
     /// If `self` is a NaN, then a NaN with the same payload as `self` and the sign bit of `sign` is
-    /// returned. Note, however, that conserving the sign bit on NaN across arithmetical operations
-    /// is not generally guaranteed. See [specification of NaN bit
-    /// patterns](primitive@f32#nan-bit-patterns) for more info.
+    /// returned.
+    ///
+    /// If `sign` is a NaN, then this operation will still carry over its sign into the result. Note
+    /// that IEEE 754 doesn't assign any meaning to the sign bit in case of a NaN, and as Rust
+    /// doesn't guarantee that the bit pattern of NaNs are conserved over arithmetic operations, the
+    /// result of `copysign` with `sign` being a NaN might produce an unexpected or non-portable
+    /// result. See the [specification of NaN bit patterns](primitive@f32#nan-bit-patterns) for more
+    /// info.
     ///
     /// # Examples
     ///
diff --git a/library/std/src/f16.rs b/library/std/src/f16.rs
index 033a3d45009..b2cd5fae9d0 100644
--- a/library/std/src/f16.rs
+++ b/library/std/src/f16.rs
@@ -249,9 +249,14 @@ impl f16 {
     ///
     /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise equal to `-self`.
     /// If `self` is a NaN, then a NaN with the same payload as `self` and the sign bit of `sign` is
-    /// returned. Note, however, that conserving the sign bit on NaN across arithmetical operations
-    /// is not generally guaranteed. See [specification of NaN bit
-    /// patterns](primitive@f32#nan-bit-patterns) for more info.
+    /// returned.
+    ///
+    /// If `sign` is a NaN, then this operation will still carry over its sign into the result. Note
+    /// that IEEE 754 doesn't assign any meaning to the sign bit in case of a NaN, and as Rust
+    /// doesn't guarantee that the bit pattern of NaNs are conserved over arithmetic operations, the
+    /// result of `copysign` with `sign` being a NaN might produce an unexpected or non-portable
+    /// result. See the [specification of NaN bit patterns](primitive@f32#nan-bit-patterns) for more
+    /// info.
     ///
     /// # Examples
     ///
diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs
index 35c2a77b533..cafbe9761da 100644
--- a/library/std/src/f32.rs
+++ b/library/std/src/f32.rs
@@ -228,9 +228,14 @@ impl f32 {
     ///
     /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise equal to `-self`.
     /// If `self` is a NaN, then a NaN with the same payload as `self` and the sign bit of `sign` is
-    /// returned. Note, however, that conserving the sign bit on NaN across arithmetical operations
-    /// is not generally guaranteed. See [specification of NaN bit
-    /// patterns](primitive@f32#nan-bit-patterns) for more info.
+    /// returned.
+    ///
+    /// If `sign` is a NaN, then this operation will still carry over its sign into the result. Note
+    /// that IEEE 754 doesn't assign any meaning to the sign bit in case of a NaN, and as Rust
+    /// doesn't guarantee that the bit pattern of NaNs are conserved over arithmetic operations, the
+    /// result of `copysign` with `sign` being a NaN might produce an unexpected or non-portable
+    /// result. See the [specification of NaN bit patterns](primitive@f32#nan-bit-patterns) for more
+    /// info.
     ///
     /// # Examples
     ///
diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs
index c177f74a97e..fba283e3a44 100644
--- a/library/std/src/f64.rs
+++ b/library/std/src/f64.rs
@@ -228,9 +228,14 @@ impl f64 {
     ///
     /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise equal to `-self`.
     /// If `self` is a NaN, then a NaN with the same payload as `self` and the sign bit of `sign` is
-    /// returned. Note, however, that conserving the sign bit on NaN across arithmetical operations
-    /// is not generally guaranteed. See [specification of NaN bit
-    /// patterns](primitive@f32#nan-bit-patterns) for more info.
+    /// returned.
+    ///
+    /// If `sign` is a NaN, then this operation will still carry over its sign into the result. Note
+    /// that IEEE 754 doesn't assign any meaning to the sign bit in case of a NaN, and as Rust
+    /// doesn't guarantee that the bit pattern of NaNs are conserved over arithmetic operations, the
+    /// result of `copysign` with `sign` being a NaN might produce an unexpected or non-portable
+    /// result. See the [specification of NaN bit patterns](primitive@f32#nan-bit-patterns) for more
+    /// info.
     ///
     /// # Examples
     ///