Auto merge of #31510 - dikaiosune:master, r=bluss

Since a lexicographic ordering of a struct could vary based on which struct members are compared first, I ended up doing some testing to ensure that the behavior when deriving these traits was what I expected (ordered based on the top to bottom order of declaration of the members). I wanted to add this little bit of documentation to potentially save someone else the same effort. That is, assuming that my testing correctly reflects the intended behavior of the compiler.

r? @steveklabnik

Author: bors

src/libcore/cmp.rs

@@ -165,9 +165,8 @@ impl Ordering {
 /// - total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true; and
 /// - transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`.
 ///
-/// When this trait is `derive`d, it produces a lexicographic ordering.
-///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]`. When `derive`d, it will produce a lexicographic
+/// ordering based on the top-to-bottom declaration order of the struct's members.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Ord: Eq + PartialOrd<Self> {
     /// This method returns an `Ordering` between `self` and `other`.
@@ -225,7 +224,8 @@ impl PartialOrd for Ordering {
 /// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 ==
 /// false` (cf. IEEE 754-2008 section 5.11).
 ///
-/// This trait can be used with `#[derive]`.
+/// This trait can be used with `#[derive]`. When `derive`d, it will produce an ordering
+/// based on the top-to-bottom declaration order of the struct's members.
 #[lang = "ord"]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait PartialOrd<Rhs: ?Sized = Self>: PartialEq<Rhs> {