Add precise definitions and limits for all calendars

components/calendar/src/cal/buddhist.rs

@@ -31,6 +31,12 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything
+/// except year numbering. This is the civil calendar used in Thailand from the year 1941 onwards,
+/// but the algorithm is extended proleptically before that.
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Buddhist;
 

components/calendar/src/cal/chinese.rs

@@ -80,6 +80,11 @@ mod simple;
 ///
 /// This calendar is currently in a preview state: formatting for this calendar is not
 /// going to be perfect.
+///
+/// # Precise definition and limits
+///
+/// This calendar generically covers any Chinese-style lunisolar calendar with twelve months, and leap months possible
+/// after any month (at most once per year). Individual variants [`China`] and [`Korea`] contain more information.
 #[derive(Clone, Debug, Default, Copy, PartialEq, Eq, PartialOrd, Ord)]
 #[allow(clippy::exhaustive_structs)] // newtype
 pub struct LunarChinese<X>(pub X);
@@ -138,11 +143,17 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed
 
 /// The [`Rules`] used in China.
 ///
-/// This type agrees with the official data published by the
+/// # Precise definition and limits
+///
+/// This calendar is the traditional Chinese lunar calendar as used
+/// in China as of the publication date of this crate.
+/// This takes a best-effort approach future dates as used in the region.
+///
+/// This calendar agrees with the official data published by the
 /// [Purple Mountain Observatory for the years 1900-2025], as well as with
 /// the data published by the [Hong Kong Observatory for the years 1901-2100].
 ///
-/// For years since 1912, this uses the [GB/T 33661-2017] rules.
+/// For years since 1912, this uses the official [GB/T 33661-2017] rules.
 /// As accurate computation is computationally expensive, years until
 /// 2100 are precomputed, and after that this type regresses to a simplified
 /// calculation. If accuracy beyond 2100 is required, clients
@@ -155,6 +166,11 @@ pub trait Rules: Clone + core::fmt::Debug + crate::cal::scaffold::UnstableSealed
 /// required before 1900, clients can implement their own [`Rules`] type
 /// using data such as from the excellent compilation by [Yuk Tung Liu].
 ///
+/// The precise behavior of this calendar may change in the future if:
+/// - New ground truth is established by published government sources
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand or reduce the range where we are handling past dates.
+///
 /// [Purple Mountain Observatory for the years 1900-2025]: http://www.pmo.cas.cn/xwdt2019/kpdt2019/202203/P020250414456381274062.pdf
 /// [Hong Kong Observatory for the years 1901-2100]: https://www.hko.gov.hk/en/gts/time/conversion.htm
 /// [GB/T 33661-2017]: China::gb_t_33661_2017
@@ -279,6 +295,12 @@ impl Rules for China {
 
 /// The [`Rules`] used in [Korea](https://en.wikipedia.org/wiki/Korean_calendar).
 ///
+/// # Precise definition and limits
+///
+/// This calendar is the traditional Korean lunar calendar as used
+/// in Korea as of the publication date of this crate.
+/// This takes a best-effort approach future dates as used in the region.
+///
 /// This type agrees with the official data published by the
 /// [Korea Astronomy and Space Science Institute for the years 1900-2050].
 ///
@@ -297,11 +319,18 @@ impl Rules for China {
 /// their own [`Rules`] type using data such as from the excellent compilation
 /// by [Yuk Tung Liu].
 ///
+/// The precise behavior of this calendar may change in the future if:
+/// - New ground truth is established by published government sources
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand/reduce the range where we are handling past dates.
+///
 /// [Korea Astronomy and Space Science Institute for the years 1900-2050]: https://astro.kasi.re.kr/life/pageView/5
 /// [adapted GB/T 33661-2017]: Korea::adapted_gb_t_33661_2017
 /// [GB/T 33661-2017]: China::gb_t_33661_2017
 /// [Yuk Tung Liu]: https://ytliu0.github.io/ChineseCalendar/table.html
 ///
+/// # Example
+///
 /// ```rust
 /// use icu::calendar::cal::LunarChinese;
 /// use icu::calendar::Date;

components/calendar/src/cal/coptic.rs

@@ -34,6 +34,12 @@ use tinystr::tinystr;
 ///
 /// This calendar supports 13 solar month codes (`"M01" - "M13"`), with `"M13"` being used for the short epagomenal month
 /// at the end of the year.
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that has 13 months, with a leap day in
+/// the 13th month every 4 years. It is used by the Coptic Orthodox Church as of the publication date
+/// of this crate, and extends proleptically before the time of its introduction.
 #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Coptic;

components/calendar/src/cal/ethiopian.rs

@@ -57,7 +57,12 @@ pub enum EthiopianEraStyle {
 ///
 /// This calendar supports 13 solar month codes (`"M01" - "M13"`), with `"M13"` being used for the short epagomenal month
 /// at the end of the year.
-// The bool specifies whether dates should be in the Amete Alem era scheme
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that has 13 months, with a leap day in
+/// the 13th month every 4 years. It is used as a civil calendar in Ethiopia as of the publication date
+/// of this crate, and extends proleptically before the time of its introduction.
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Ethiopian(EthiopianEraStyle);
 

components/calendar/src/cal/gregorian.rs

@@ -102,6 +102,13 @@ impl GregorianYears for CeBce {
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that has 12 months, with a leap day in the
+/// 2nd month every 4 and 400 years (but not every 100 years). As of 2025 it is a widely used civil calendar
+/// in most countries, including the UN. The Gregorian calendar was adopted gradually starting in the 1500s,
+/// this calendar extends proleptically before that.
 #[derive(Copy, Clone, Debug, Default)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Gregorian;

components/calendar/src/cal/hebrew.rs

@@ -36,6 +36,17 @@ use calendrical_calculations::rata_die::RataDie;
 /// [`MonthInfo`] has slightly divergent behavior: because the regular month Adar is formatted
 /// as "Adar II" in a leap year, this calendar will produce the special code `"M06L"` in any [`MonthInfo`]
 /// objects it creates.
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a lunar calendar with a leap 6th month every
+/// 3rd, 6th, 8th, 11th, 14th, 17th, and 19th years (in a 19-year Metonic cycle). It is used as a
+/// liturgical calendar in Judaism as of the publication date of this crate.
+/// This calendar uses the the "civil new year" variant where Tishrei is the first month of the year.
+/// The precise algorithm used has [changed over time], with the modern one being in place
+/// since about 776 CE. This calendar extends that algorithm proleptically before that.
+///
+/// [changed over time]: https://hakirah.org/vol20AjdlerAppendices.pdf
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord, Default)]
 #[allow(clippy::exhaustive_structs)] // unit struct
 pub struct Hebrew;

components/calendar/src/cal/hijri.rs

@@ -47,6 +47,16 @@ mod ummalqura_data;
 ///
 /// This calendar is a pure lunar calendar with no leap months. It uses month codes
 /// `"M01" - "M12"`.
+///
+/// # Precise definition and limits
+///
+/// This calendar generically covers any pure lunar calendar used liturgically in Islam,
+/// with 12 months each of length 29 or 30, with an epoch intended to mark the Hijrah in 622 CE.
+///
+/// In practice, this calendar can be backed by a precise algorithm, a lookup in official tables,
+/// astronomical simulation, or pure observation.
+///
+/// Further details can be found on individual calendar types.
 #[derive(Clone, Debug, Default, Copy)]
 #[allow(clippy::exhaustive_structs)] // newtype
 pub struct Hijri<S>(pub S);
@@ -111,6 +121,14 @@ pub trait Rules: Clone + Debug + crate::cal::scaffold::UnstableSealed {
 ///
 /// This corresponds to the `"islamic-rgsa"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier)
 /// if constructed with [`Hijri::new_simulated_mecca()`].
+///
+/// # Precise definition and limits
+///
+/// This calendar simulates the lunar cycle for a given location. This currently
+/// simulates the calendar for all time using the same calculations, but we may
+/// in the future introduce approximations for non-modern dates.
+///
+/// The precise behavior of this calendar for any and all dates may change in the future.
 #[derive(Copy, Clone, Debug)]
 pub struct AstronomicalSimulation {
     pub(crate) location: SimulatedLocation,
@@ -227,15 +245,21 @@ impl Rules for AstronomicalSimulation {
 
 /// [`Hijri`] [`Rules`] for the [Umm al-Qura](https://en.wikipedia.org/wiki/Islamic_calendar#Saudi_Arabia's_Umm_al-Qura_calendar) calendar.
 ///
+/// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier).
+///
+/// # Precise definition and limits
+///
+/// This calendar represents the Umm al-Qura calendar defined by the Kingdom of Saudi Arabia.
+///
 /// From the start of 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO), this
 /// `Rules` implementation uses Umm al-Qura month lengths obtained from
 /// [KACST](https://kacst.gov.sa/). Outside this range, this implementation falls back to
 /// [`TabularAlgorithm`] with [`TabularAlgorithmLeapYears::TypeII`] and [`TabularAlgorithmEpoch::Friday`].
 ///
-/// Future versions of this crate may extend the range that uses month length data from the
-/// calendar authority.
-///
-/// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier).
+/// The precise behavior of this calendar may change in the future if:
+/// - New ground truth is established by published government sources
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand or reduce the range where we are handling past dates.
 #[derive(Copy, Clone, Debug, Default)]
 #[non_exhaustive]
 pub struct UmmAlQura;
@@ -311,6 +335,11 @@ impl Rules for UmmAlQura {
 ///
 /// When constructed with [`TabularAlgorithmLeapYears::TypeII`], and either [`TabularAlgorithmEpoch::Friday`] or [`TabularAlgorithmEpoch::Thursday`],
 /// this corresponds to the `"islamic-civil"` and `"islamic-tbla"` [CLDR calendars](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier) respectively.
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically based on the algorithm selected by the choice of [`TabularAlgorithmLeapYears`],
+/// and the epoch selected by the choice of [`TabularAlgorithmEpoch`].
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq, PartialOrd, Ord)]
 pub struct TabularAlgorithm {
     pub(crate) leap_years: TabularAlgorithmLeapYears,

components/calendar/src/cal/indian.rs

@@ -27,6 +27,13 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that has 12 months, as used alongside the
+/// Gregorian calendar by the Government of India by the name "Śaka calendar" as of publication date of this crate.
+///
+/// The Śaka calendar was introduced in 1957, but this calendar extends proleptically before that.
 #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Indian;

components/calendar/src/cal/iso.rs

@@ -21,6 +21,11 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar
+/// in everything except the way eras are handled.
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Iso;

components/calendar/src/cal/japanese.rs

@@ -39,6 +39,12 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`M01` - `M12`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything
+/// except year numbering. This is the civil calendar used in Japan from 1873, this calendar extends proleptically
+/// before that.
 #[derive(Clone, Debug, Default)]
 pub struct Japanese {
     eras: DataPayload<CalendarJapaneseModernV1>,

components/calendar/src/cal/julian.rs

@@ -59,6 +59,12 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar with a leap month every 4 years, as was used
+/// by the Roman empire in 4 CE. That algorithm is extended proleptically before and after its period of use.
+///
 #[derive(Copy, Clone, Debug, Hash, Default, Eq, PartialEq, PartialOrd, Ord)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Julian;

components/calendar/src/cal/persian.rs

@@ -29,6 +29,20 @@ use calendrical_calculations::rata_die::RataDie;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined as a solar calendar which uses the astronomical vernal equinox as its new year, and
+/// is the official calendar of the Islamic Republic of Iran as of the publication date of this crate. This calendar was introduced in Iran in 1925,
+/// but the astronomical calculations are extended proleptically before that.
+///
+/// As these are pure solar computations, the astronomical calculations can be treated as a relatively
+/// precise algorithm and there is much less need to match ground truth. Nevertheless, in the event that the calculations
+/// disagree with the ground truth of calendar usage in Iran, the ground truth will prevail.
+///
+/// The underlying implementation uses a cyclic approximation with overrides to match the precise astronomic calculations
+/// for the years 1178-3500 AP. Outside of that range one can expect this calendar implementation to no longer
+/// accurately match the astronomical calculations.
 #[derive(Copy, Clone, Debug, Default, Hash, Eq, PartialEq, PartialOrd, Ord)]
 #[allow(clippy::exhaustive_structs)]
 pub struct Persian;

components/calendar/src/cal/roc.rs

@@ -29,6 +29,12 @@ use tinystr::tinystr;
 /// # Month codes
 ///
 /// This calendar supports 12 solar month codes (`"M01" - "M12"`)
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that is identical to the proleptic Gregorian calendar in everything
+/// except year numbering. This is the civil calendar used in the Republic of China from the year 1912 onwards,
+/// but the algorithm is extended proleptically before that.
 #[derive(Copy, Clone, Debug, Default)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct Roc;