turn comment on PartialOrd into a doc comment

Might be nice to have it readable in the documentation, not just the
source!

1 files changed, 16 insertions, 13 deletions

diff --git a/src/gamedata.rs b/src/gamedata.rs
index 9f0f9d4..a956478 100644
--- a/src/gamedata.rs
+++ b/src/gamedata.rs
@@ -358,21 +358,24 @@ macro_rules! ordering_group {
     }
 }
 
-// We could implement (or even derive) PartialOrd for all bosses, but there is no "canonical" order
-// (do fractal bosses come before raid bosses or after?). This implements a conservative order,
-// such that at least the bosses that appear in a single raid wing/fractal are ordered relative to
-// each other, but there is no order between different wings. This still allows some useful cases
-// (like sorting bosses within a wing).
-//
-// There are some edge cases, like the Wing 5 events (Eater/Eyes/Broken King) and Adina/Sabir,
-// which technically happen at the same time, but we're just defining a fixed order for those here.
-//
-// In the future, this implementation might be expanded to a total order, but by keeping it a
-// partial order for now we can implement the cases that are clear (bosses within a wing) while
-// allowing future extensions in a backwards-compatible way (once we figured out how we want to
-// order the different wings/strikes/fractals).
+/// Implements a partial order for encounters.
+///
+/// The order is chosen to be conservative, as there is no "canonical" order of all encounters in
+/// the game.
+///
+/// The ordering rules are:
+/// * An order is only defined between encounters of the same raid wing/fractal.
+/// * An encounter A is "less" than an encounter B if A occurs before B in the raid/fractal.
+/// * Encounters that are in the same wing but have no strict "happens before" relation (such as
+///   Cardinal Adina and Cardinal Sabir) have an arbitrary order defined.
+///
+/// Future versions might extend this order to introduce inter-wing comparisons or a full [`Ord`]
+/// instance.
 impl PartialOrd for Encounter {
     fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+        // Keep in mind that this is a partial order, not a weak order! In particular, we cannot
+        // have bosses compare as equal if they are not the same (even if that would be nice for
+        // Wing 5/Wing 7).
         use Encounter::*;
         ordering_group!(*self, *other;
             // Raids