Rollup merge of #129559 - RalfJung:float-nan-semantics, r=thomcc

float types: document NaN bit pattern guarantees

Part of https://github.com/rust-lang/rust/issues/128288: document the guarantees we make for NaN bit patterns.

Cc ``@tgross35``

library/std/src/f128.rs

@@ -248,11 +248,11 @@ impl f128 {
     /// Returns a number composed of the magnitude of `self` and the sign of
     /// `sign`.
     ///
-    /// 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 sign bit of
-    /// `sign` is returned. Note, however, that conserving the sign bit on NaN
-    /// across arithmetical operations is not generally guaranteed.
-    /// See [explanation of NaN as a special value](primitive@f128) for more info.
+    /// 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.
     ///
     /// # Examples
     ///

library/std/src/f16.rs

@@ -247,11 +247,11 @@ impl f16 {
     /// Returns a number composed of the magnitude of `self` and the sign of
     /// `sign`.
     ///
-    /// 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 sign bit of
-    /// `sign` is returned. Note, however, that conserving the sign bit on NaN
-    /// across arithmetical operations is not generally guaranteed.
-    /// See [explanation of NaN as a special value](primitive@f16) for more info.
+    /// 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.
     ///
     /// # Examples
     ///

library/std/src/f32.rs

@@ -226,11 +226,11 @@ impl f32 {
     /// Returns a number composed of the magnitude of `self` and the sign of
     /// `sign`.
     ///
-    /// 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 sign bit of
-    /// `sign` is returned. Note, however, that conserving the sign bit on NaN
-    /// across arithmetical operations is not generally guaranteed.
-    /// See [explanation of NaN as a special value](primitive@f32) for more info.
+    /// 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.
     ///
     /// # Examples
     ///

library/std/src/f64.rs

@@ -226,11 +226,11 @@ impl f64 {
     /// Returns a number composed of the magnitude of `self` and the sign of
     /// `sign`.
     ///
-    /// 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 sign bit of
-    /// `sign` is returned. Note, however, that conserving the sign bit on NaN
-    /// across arithmetical operations is not generally guaranteed.
-    /// See [explanation of NaN as a special value](primitive@f32) for more info.
+    /// 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.
     ///
     /// # Examples
     ///