Rollup merge of #93403 - nagisa:total-cmp-review, r=joshtriplett

review the total_cmp documentation

The documentation has been restructured to split out a brief summary
paragraph out from the following elaborating paragraphs.

I also attempted my hand at wording improvements and adding articles
where I felt them missing, but being non-native english speaker these
may need more thorough review.

cc https://github.com/rust-lang/rust/issues/72599

2 files changed, 54 insertions, 38 deletions

diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs
index 0b8ed0cc174..d8dcfdafa8d 100644
--- a/library/core/src/num/f32.rs
+++ b/library/core/src/num/f32.rs
@@ -1008,29 +1008,37 @@ impl f32 {
         Self::from_bits(u32::from_ne_bytes(bytes))
     }
 
-    /// Returns an ordering between self and other values.
+    /// Return the ordering between `self` and `other`.
+    ///
     /// Unlike the standard partial comparison between floating point numbers,
     /// this comparison always produces an ordering in accordance to
-    /// the totalOrder predicate as defined in IEEE 754 (2008 revision)
-    /// floating point standard. The values are ordered in following order:
-    /// - Negative quiet NaN
-    /// - Negative signaling NaN
-    /// - Negative infinity
-    /// - Negative numbers
-    /// - Negative subnormal numbers
-    /// - Negative zero
-    /// - Positive zero
-    /// - Positive subnormal numbers
-    /// - Positive numbers
-    /// - Positive infinity
-    /// - Positive signaling NaN
-    /// - Positive quiet NaN
-    ///
-    /// Note that this function does not always agree with the [`PartialOrd`]
-    /// and [`PartialEq`] implementations of `f32`. In particular, they regard
-    /// negative and positive zero as equal, while `total_cmp` doesn't.
+    /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision)
+    /// floating point standard. The values are ordered in the following sequence:
+    ///
+    /// - negative quiet NaN
+    /// - negative signaling NaN
+    /// - negative infinity
+    /// - negative numbers
+    /// - negative subnormal numbers
+    /// - negative zero
+    /// - positive zero
+    /// - positive subnormal numbers
+    /// - positive numbers
+    /// - positive infinity
+    /// - positive signaling NaN
+    /// - positive quiet NaN.
+    ///
+    /// The ordering established by this function does not always agree with the
+    /// [`PartialOrd`] and [`PartialEq`] implementations of `f32`. For example,
+    /// they consider negative and positive zero equal, while `total_cmp`
+    /// doesn't.
+    ///
+    /// The interpretation of the signaling NaN bit follows the definition in
+    /// the IEEE 754 standard, which may not match the interpretation by some of
+    /// the older, non-conformant (e.g. MIPS) hardware implementations.
     ///
     /// # Example
+    ///
     /// ```
     /// #![feature(total_cmp)]
     /// struct GoodBoy {
diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs
index 5a3cd2a4b92..7c2f51ff646 100644
--- a/library/core/src/num/f64.rs
+++ b/library/core/src/num/f64.rs
@@ -1024,29 +1024,37 @@ impl f64 {
         Self::from_bits(u64::from_ne_bytes(bytes))
     }
 
-    /// Returns an ordering between self and other values.
+    /// Return the ordering between `self` and `other`.
+    ///
     /// Unlike the standard partial comparison between floating point numbers,
     /// this comparison always produces an ordering in accordance to
-    /// the totalOrder predicate as defined in IEEE 754 (2008 revision)
-    /// floating point standard. The values are ordered in following order:
-    /// - Negative quiet NaN
-    /// - Negative signaling NaN
-    /// - Negative infinity
-    /// - Negative numbers
-    /// - Negative subnormal numbers
-    /// - Negative zero
-    /// - Positive zero
-    /// - Positive subnormal numbers
-    /// - Positive numbers
-    /// - Positive infinity
-    /// - Positive signaling NaN
-    /// - Positive quiet NaN
-    ///
-    /// Note that this function does not always agree with the [`PartialOrd`]
-    /// and [`PartialEq`] implementations of `f64`. In particular, they regard
-    /// negative and positive zero as equal, while `total_cmp` doesn't.
+    /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision)
+    /// floating point standard. The values are ordered in the following sequence:
+    ///
+    /// - negative quiet NaN
+    /// - negative signaling NaN
+    /// - negative infinity
+    /// - negative numbers
+    /// - negative subnormal numbers
+    /// - negative zero
+    /// - positive zero
+    /// - positive subnormal numbers
+    /// - positive numbers
+    /// - positive infinity
+    /// - positive signaling NaN
+    /// - positive quiet NaN.
+    ///
+    /// The ordering established by this function does not always agree with the
+    /// [`PartialOrd`] and [`PartialEq`] implementations of `f64`. For example,
+    /// they consider negative and positive zero equal, while `total_cmp`
+    /// doesn't.
+    ///
+    /// The interpretation of the signaling NaN bit follows the definition in
+    /// the IEEE 754 standard, which may not match the interpretation by some of
+    /// the older, non-conformant (e.g. MIPS) hardware implementations.
     ///
     /// # Example
+    ///
     /// ```
     /// #![feature(total_cmp)]
     /// struct GoodBoy {