Rollup merge of #78627 - est31:total_cmp_no_superset, r=m-ou-se

Point out that total_cmp is no strict superset of partial comparison

Partial comparison and total_cmp are not equal. This helps
preventing the mistake of creating float wrappers that
base their Ord impl on total_cmp and their PartialOrd impl on
the PartialOrd impl of the float type. PartialOrd and Ord
[are required to agree with each other](https://doc.rust-lang.org/std/cmp/trait.Ord.html#how-can-i-implement-ord).

2 files changed, 8 insertions, 0 deletions

diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs
index bf7c87f685d..86e6352d132 100644
--- a/library/core/src/num/f32.rs
+++ b/library/core/src/num/f32.rs
@@ -876,6 +876,10 @@ impl f32 {
     /// - 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.
+    ///
     /// # Example
     /// ```
     /// #![feature(total_cmp)]
diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs
index e31e176ba1b..9b1405b479f 100644
--- a/library/core/src/num/f64.rs
+++ b/library/core/src/num/f64.rs
@@ -890,6 +890,10 @@ impl f64 {
     /// - 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.
+    ///
     /// # Example
     /// ```
     /// #![feature(total_cmp)]