From 828febf9e0fbd653cdcb2a949ec3defded69dc3f Mon Sep 17 00:00:00 2001
From: Ariel Davis <ariel.z.davis@icloud.com>
Date: Sat, 15 Jan 2022 20:24:38 -0800
Subject: [PATCH] Clear up discriminants with more examples

---
 library/core/src/cmp.rs | 70 ++++++++++++++++++++++++++++++-----------
 1 file changed, 52 insertions(+), 18 deletions(-)

diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs
index ef81e8736ed..a404b699de1 100644
--- a/library/core/src/cmp.rs
+++ b/library/core/src/cmp.rs
@@ -661,20 +661,37 @@ fn clone_from(&mut self, other: &Self) {
 ///
 /// ## Derivable
 ///
-/// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a
-/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering based on the top-to-bottom declaration order of the struct's members.
-/// When `derive`d on enums, variants are ordered by their top-to-bottom discriminant order.
-/// This means variants at the top are less than variants at the bottom.
-/// Here's an example:
+/// This trait can be used with `#[derive]`.
 ///
+/// When `derive`d on structs, it will produce a
+/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering
+/// based on the top-to-bottom declaration order of the struct's members.
+///
+/// When `derive`d on enums, variants are ordered by their discriminants.
+/// By default, the discriminant is smallest for variants at the top, and
+/// largest for variants at the bottom. Here's an example:
+///
+/// ```
+/// #[derive(PartialEq, Eq, PartialOrd, Ord)]
+/// enum E {
+///     Top,
+///     Bottom,
+/// }
+///
+/// assert!(E::Top < E::Bottom);
+/// ```
+///
+/// However, manually setting the discriminants can override this default
+/// behavior:
+////
 /// ```
 /// #[derive(PartialEq, Eq, PartialOrd, Ord)]
-/// enum Size {
-///     Small,
-///     Large,
+/// enum E {
+///     Top = 2,
+///     Bottom = 1,
 /// }
 ///
-/// assert!(Size::Small < Size::Large);
+/// assert!(E::Bottom < E::Top);
 /// ```
 ///
 /// ## Lexicographical comparison
@@ -895,20 +912,37 @@ fn partial_cmp(&self, other: &Ordering) -> Option<Ordering> {
 ///
 /// ## Derivable
 ///
-/// This trait can be used with `#[derive]`. When `derive`d on structs, it will produce a
-/// lexicographic ordering based on the top-to-bottom declaration order of the struct's members.
-/// When `derive`d on enums, variants are ordered by their top-to-bottom discriminant order.
-/// This means variants at the top are less than variants at the bottom.
-/// Here's an example:
+/// This trait can be used with `#[derive]`.
+///
+/// When `derive`d on structs, it will produce a
+/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering
+/// based on the top-to-bottom declaration order of the struct's members.
+///
+/// When `derive`d on enums, variants are ordered by their discriminants.
+/// By default, the discriminant is smallest for variants at the top, and
+/// largest for variants at the bottom. Here's an example:
+///
+/// ```
+/// #[derive(PartialEq, PartialOrd)]
+/// enum E {
+///     Top,
+///     Bottom,
+/// }
+///
+/// assert!(E::Top < E::Bottom);
+/// ```
 ///
+/// However, manually setting the discriminants can override this default
+/// behavior:
+////
 /// ```
 /// #[derive(PartialEq, PartialOrd)]
-/// enum Size {
-///     Small,
-///     Large,
+/// enum E {
+///     Top = 2,
+///     Bottom = 1,
 /// }
 ///
-/// assert!(Size::Small < Size::Large);
+/// assert!(E::Bottom < E::Top);
 /// ```
 ///
 /// ## How can I implement `PartialOrd`?
-- 
2.44.0