Add documentation

Author: daxpedda

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+- Use stable methods to retrieve the discriminant in `PartialOrd` and `Ord`
+  implementations. Safe methods are now also used with the `safe` crate
+  feature, significantly improving the performance there.
+
 ## [1.2.3] - 2023-08-23
 
 ### Fixed

README.md

@@ -285,11 +285,12 @@ Unions only support [`Clone`] and [`Copy`].
   default too. Without this feature [`transmute`] is
   used to convert [`Discriminant`] to a [`i32`],
   which is the underlying type.
-- `safe`: Implements [`Ord`] and [`PartialOrd`] manually. This is much
-  slower, but might be preferred if you don't trust derive-where. It also
-  replaces all cases of [`core::hint::unreachable_unchecked`] in [`Ord`],
-  [`PartialEq`] and [`PartialOrd`], which is what std uses, with
-  [`unreachable`].
+- `safe`: Implements [`Ord`] and [`PartialOrd`] on enums with a non-default
+  representation and at least one non-empty variant without unsafely
+  accessing the discriminant. This is much slower, but might be preferred if
+  you don't trust derive-where. It also replaces all cases of
+  [`core::hint::unreachable_unchecked`] in [`Ord`], [`PartialEq`] and
+  [`PartialOrd`], which is what std uses, with [`unreachable`].
 - `zeroize`: Allows deriving [`Zeroize`] and [`zeroize`][method@zeroize] on
   [`Drop`].
 - `zeroize-on-drop`: Allows deriving [`Zeroize`] and [`ZeroizeOnDrop`] and

src/lib.rs

@@ -324,11 +324,12 @@
 //!   default too. Without this feature [`transmute`](core::mem::transmute) is
 //!   used to convert [`Discriminant`](core::mem::Discriminant) to a [`i32`],
 //!   which is the underlying type.
-//! - `safe`: Implements [`Ord`] and [`PartialOrd`] manually. This is much
-//!   slower, but might be preferred if you don't trust derive-where. It also
-//!   replaces all cases of [`core::hint::unreachable_unchecked`] in [`Ord`],
-//!   [`PartialEq`] and [`PartialOrd`], which is what std uses, with
-//!   [`unreachable`].
+//! - `safe`: Implements [`Ord`] and [`PartialOrd`] on enums with a non-default
+//!   representation and at least one non-empty variant without unsafely
+//!   accessing the discriminant. This is much slower, but might be preferred if
+//!   you don't trust derive-where. It also replaces all cases of
+//!   [`core::hint::unreachable_unchecked`] in [`Ord`], [`PartialEq`] and
+//!   [`PartialOrd`], which is what std uses, with [`unreachable`].
 //! - `zeroize`: Allows deriving [`Zeroize`] and [`zeroize`][method@zeroize] on
 //!   [`Drop`].
 //! - `zeroize-on-drop`: Allows deriving [`Zeroize`] and [`ZeroizeOnDrop`] and