Remove generic CldrCalendar impl for Hijri and add update docs

components/calendar/src/types.rs

@@ -43,16 +43,19 @@ pub struct DateFields<'a> {
     pub day: Option<NonZeroU8>,
 }
 
-/// The type of year: Calendars like Chinese don't have an era and instead format with cyclic years.
+/// Information about the year. Returned by [`Date::year()`](crate::Date::year)
+///
+/// This enum supports calendars based on eras as well as calendars based on cycles.
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub enum YearInfo {
-    /// An era and a year in that era
+    /// Information about the year in calendars with eras.
+    ///
+    /// A majority of calendars use this variant.
     Era(EraYear),
-    /// A cyclic year, and the related ISO year
+    /// Information about the year in calendars with cycles.
     ///
-    /// Knowing the cyclic year is typically not enough to pinpoint a date, however cyclic calendars
-    /// don't typically use eras, so disambiguation can be done by saying things like "Year 甲辰 (2024)"
+    /// This is used in the Chinese and Dangi lunisolar calendars.
     Cyclic(CyclicYear),
 }
 
@@ -144,6 +147,9 @@ pub struct EraYear {
 }
 
 /// Year information for a year that is specified as a cyclic year
+///
+/// Knowing the cyclic year is typically not enough to pinpoint a date, however cyclic calendars
+/// don't typically use eras, so disambiguation can be done by saying things like "Year 甲辰 (2024)"
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub struct CyclicYear {
@@ -269,7 +275,7 @@ impl fmt::Display for MonthCode {
     }
 }
 
-/// Representation of a formattable month.
+/// Representation of a formattable month. Returned by [`Date::month()`](crate::Date::month)
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[non_exhaustive]
 pub struct MonthInfo {

components/datetime/src/provider/neo/mod.rs

@@ -548,7 +548,7 @@ size_test!(YearNames, year_names_v1_size, 32);
 pub enum YearNames<'data> {
     /// This calendar has a small, fixed set of eras with numeric years, this stores the era names in chronological order.
     ///
-    /// See FormattableEra for a definition of what chronological order is in this context.
+    /// See [`EraYear`](icu_calendar::types::EraYear) for a definition of what chronological order is in this context.
     FixedEras(#[cfg_attr(feature = "serde", serde(borrow))] VarZeroVec<'data, str>),
     /// This calendar has a variable set of eras with numeric years, this stores the era names mapped from
     /// era code to the name.

components/datetime/src/scaffold/calendar.rs

@@ -17,15 +17,21 @@ use icu_time::{
     DateTime, Time, TimeZoneInfo, ZonedDateTime,
 };
 
-/// A calendar that can be found in CLDR.
+/// A calendar that can be formatted with CLDR data.
 ///
-/// New implementors of this trait will likely also wish to modify `get_era_code_map()`
-/// in the CLDR transformer to support any new era maps.
+/// When formatting:
+///
+/// - The pattern is loaded from [`Self::SkeletaV1`]
+/// - The era and year names are loaded from [`Self::YearNamesV1`] and accessed based on [`YearInfo`]
+/// - The month name is loaded from [`Self::MonthNamesV1`] and accessed based on [`MonthInfo`]
 ///
 /// <div class="stab unstable">
-/// 🚫 This trait is sealed; it cannot be implemented by user code. If an API requests an item that implements this
-/// trait, please consider using a type from the implementors listed below.
+/// 🚧 This trait is considered unstable; it may change at any time, in breaking or non-breaking ways,
+/// including in SemVer minor releases. Do not implement this trait in userland unless you are prepared for things to occasionally break.
 /// </div>
+///
+/// [`YearInfo`]: icu_calendar::types::YearInfo
+/// [`MonthInfo`]: icu_calendar::types::MonthInfo
 pub trait CldrCalendar: UnstableSealed {
     /// The data marker for loading year symbols for this calendar.
     type YearNamesV1: DataMarker<DataStruct = YearNames<'static>>;
@@ -91,7 +97,19 @@ impl CldrCalendar for Indian {
     type SkeletaV1 = DatetimePatternsDateIndianV1;
 }
 
-impl<R: hijri::Rules> CldrCalendar for Hijri<R> {
+impl CldrCalendar for Hijri<hijri::UmmAlQura> {
+    type YearNamesV1 = DatetimeNamesYearHijriV1;
+    type MonthNamesV1 = DatetimeNamesMonthHijriV1;
+    type SkeletaV1 = DatetimePatternsDateHijriV1;
+}
+
+impl CldrCalendar for Hijri<hijri::TabularAlgorithm> {
+    type YearNamesV1 = DatetimeNamesYearHijriV1;
+    type MonthNamesV1 = DatetimeNamesMonthHijriV1;
+    type SkeletaV1 = DatetimePatternsDateHijriV1;
+}
+
+impl CldrCalendar for Hijri<hijri::AstronomicalSimulation> {
     type YearNamesV1 = DatetimeNamesYearHijriV1;
     type MonthNamesV1 = DatetimeNamesMonthHijriV1;
     type SkeletaV1 = DatetimePatternsDateHijriV1;
@@ -130,7 +148,9 @@ impl UnstableSealed for Ethiopian {}
 impl UnstableSealed for Gregorian {}
 impl UnstableSealed for Hebrew {}
 impl UnstableSealed for Indian {}
-impl<R: hijri::Rules> UnstableSealed for Hijri<R> {}
+impl UnstableSealed for Hijri<hijri::UmmAlQura> {}
+impl UnstableSealed for Hijri<hijri::TabularAlgorithm> {}
+impl UnstableSealed for Hijri<hijri::AstronomicalSimulation> {}
 impl UnstableSealed for Japanese {}
 impl UnstableSealed for JapaneseExtended {}
 impl UnstableSealed for Persian {}