From 2efa5c1d7b6ab82f78567db91b3644bee172c811 Mon Sep 17 00:00:00 2001
From: Sylvestre Ledru <sylvestre@debian.org>
Date: Tue, 31 Mar 2026 09:14:23 +0200
Subject: [PATCH] Add doc comments on expect_in_range and PartialEq<Zoned>

Document that expect_in_range is intended for tests/trusted contexts
and that Extended values never compare equal to a Zoned.
---
 src/lib.rs | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 74e376e..b4b3d80 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -49,6 +49,11 @@ impl ParsedDateTime {
         }
     }
 
+    /// Unwraps the `InRange` variant, panicking if this is an `Extended` value.
+    ///
+    /// This is a convenience for contexts where the caller is certain the result
+    /// is in range (e.g., tests). Prefer [`into_zoned`](Self::into_zoned) or
+    /// pattern matching in production code.
     pub fn expect_in_range(self) -> Zoned {
         self.into_zoned()
             .expect("ParsedDateTime is not representable as jiff::Zoned")
@@ -64,6 +69,7 @@ impl fmt::Display for ParsedDateTime {
     }
 }
 
+/// An `Extended` value never compares equal to a `Zoned`.
 impl PartialEq<Zoned> for ParsedDateTime {
     fn eq(&self, other: &Zoned) -> bool {
         match self {