Remove generic CldrCalendar impl for Hijri and add update docs

components/calendar/src/types.rs

@@ -43,16 +43,23 @@ 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 by the [`LunarChinese`] calendar.
+    ///
+    /// [`LunarChinese`]: crate::cal::LunarChinese
     Cyclic(CyclicYear),
 }
 
@@ -144,6 +151,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 {
@@ -270,6 +280,8 @@ impl fmt::Display for MonthCode {
 }
 
 /// 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

@@ -546,9 +546,8 @@ size_test!(YearNames, year_names_v1_size, 32);
 #[cfg_attr(feature = "serde", derive(serde::Deserialize))]
 #[yoke(prove_covariance_manually)]
 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.
+    /// This calendar has a small, fixed set of eras with numeric years. Eras are stored
+    /// according to their [era index](icu_calendar::types::EraYear::era_index).
     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 {}