Add more docs on Date's range errors (#7689)

Fixes #7076 (I think
everything else there is resolved)

Decided to add a nice section on `Date` that the other docs can all
point to. I chose to publicize our range but clearly document it as
subject to change within limits.

We _may_ wish to publicly expose `VALID_RD_RANGE`.

Author: Manishearth

components/calendar/src/date.rs

@@ -103,6 +103,25 @@ impl<C> Deref for Ref<'_, C> {
 /// 3. From a RFC 9557 string via [`Self::try_from_str()`]
 /// 4. From a [`RataDie`] via [`Self::from_rata_die()`]
 ///
+/// # Date ranges
+///
+/// *Most* `Date` constructors will refuse to construct dates from `year` values outside of the range
+/// `-9999..=9999`, however since that is a per-calendar value, it is possible to escape that range
+/// by changing the era/calendar. Furthermore, this is not the case for [`Date::try_from_fields`] and
+/// date arithmetic APIs: these APIs let you construct dates outside of that range.
+///
+/// `Date` types have a fundamental range invariant as well, and ICU4X will refuse to construct
+/// dates outside of that range, regardless of the calendar.
+/// ICU4X APIs will return an `Overflow` error (e.g. `DateAddError::Overflow`) in these cases, or clamp
+/// in the case of `Date::from_rata_die()`.
+///
+/// This range is currently dates with an ISO year between `-999_999..=999_999`, but
+/// ICU4X reserves the right to change these bounds in the future.
+///
+/// Since `icu_calendar` is intended to be usable by implementors of the ECMA Temporal specification,
+/// this range will never be smaller than Temporal's validity range, which roughly maps to ISO years
+/// -271,821 to 275,760 (precisely speaking, it is ± 100,000,000 days from January 1, 1970).
+///
 /// # Examples
 ///
 /// ```rust
@@ -147,6 +166,9 @@ impl<A: AsCalendar> Date<A> {
     /// and the month as either ordinal or month code. It can constrain out-of-bounds values
     /// and fill in missing fields. See [`DateFromFieldsOptions`] for more information.
     ///
+    /// This API will not construct dates outside of the fundamental range described on the [`Date`] type
+    /// instead returning [`DateFromFieldsError::Overflow`].
+    ///
     /// # Examples
     ///
     /// ```
@@ -189,8 +211,11 @@ impl<A: AsCalendar> Date<A> {
 
     /// Construct a date from a [`RataDie`] and a calendar.
     ///
-    /// This method is guaranteed to round trip with [`Date::to_rata_die`]. Inputs
-    /// that were not produced by [`Date::to_rata_die`] might be clamped:
+    /// This method is guaranteed to round trip with [`Date::to_rata_die`].
+    ///
+    /// For other values, This API will not construct dates outside of the fundamental range
+    /// described on the [`Date`] type instead clamping the result:
+    ///
     /// ```rust
     /// use icu::calendar::{Date, Gregorian, types::RataDie};
     ///
@@ -315,6 +340,9 @@ impl<A: AsCalendar> Date<A> {
 
     /// Add a `duration` to this date, mutating it
     ///
+    /// This API will not construct dates outside of the fundamental range described on the [`Date`] type,
+    /// instead returning [`DateAddError::Overflow`].
+    ///
     /// <div class="stab unstable">
     /// 🚧 This code is considered unstable; it may change at any time, in breaking or non-breaking ways,
     /// including in SemVer minor releases. Do not use this type unless you are prepared for things to occasionally break.
@@ -338,7 +366,10 @@ impl<A: AsCalendar> Date<A> {
         Ok(())
     }
 
-    /// Add a `duration` to this date, returning the new one
+    /// Add a `duration` to this date, returning the new one.
+    ///
+    /// This API will not construct dates outside of the fundamental range described on the [`Date`] type,
+    /// instead returning [`DateAddError::Overflow`].
     ///
     /// <div class="stab unstable">
     /// 🚧 This code is considered unstable; it may change at any time, in breaking or non-breaking ways,

components/calendar/src/error.rs

@@ -433,7 +433,8 @@ mod unstable {
         /// ```
         #[displaydoc("Not enough fields")]
         NotEnoughFields,
-        /// The date is out of range.
+        /// The date is out of range (see docs on [`Date`](crate::Date)
+        /// for more information about `Date`'s fundamental range invariant).
         ///
         /// # Examples
         ///
@@ -536,7 +537,8 @@ mod unstable {
         /// ```
         #[displaydoc("The specified month exists in this calendar, but not for this year")]
         MonthNotInYear,
-        /// The date is out of range.
+        /// The date is out of range (see docs on [`Date`](crate::Date)
+        /// for more information about `Date`'s fundamental range invariant).
         ///
         /// # Examples
         ///