Add precise definitions and limits for all calendars

Author: Manishearth

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 1912 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

@@ -84,6 +84,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 East Asian-style lunisolar calendar with twelve months, and leap months possible
+/// after any month. 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);
@@ -141,11 +146,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 intended to represent the traditional Chinese lunar calendar as used
+/// officially in the People's Republic of China as of 2025. This takes a best-effort approach
+/// to match past and future dates as used in the region for the year 1900 onwards.
+///
+/// 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 official the [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
@@ -158,6 +169,12 @@ 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:
+/// - The ground truth in China changes, either through published government sources or most almanacs
+/// - Future data is published that we wish to incorporate
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand 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
@@ -277,6 +294,12 @@ impl Rules for China {
 
 /// The [`Rules`] used in [Korea](https://en.wikipedia.org/wiki/Korean_calendar).
 ///
+/// # Precise definition and limits
+///
+/// This calendar is intended to represent the traditional Korean lunar calendar as used
+/// officially in the Republic of Korea as of 2025. This takes a best-effort approach
+/// to match past and future dates as used in the region for the year 1900 onwards.
+///
 /// This type agrees with the official data published by the
 /// [Korea Astronomy and Space Science Institute for the years 1900-2050].
 ///
@@ -295,11 +318,19 @@ 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:
+/// - The ground truth in South Korea changes, either through published government sources or most almanacs
+/// - Future data is published that we wish to incorporate
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand 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

@@ -35,6 +35,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, as used by the Coptic orthodox church as of 2025. This calendar 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

@@ -58,6 +58,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.
+///
+/// # Precise definition and limits
+///
+/// This calendar is defined algorithmically as a solar calendar that has 13 months,
+/// as used as a civil calendar in Ethiopia as of 2025. This calendar extends proleptically
+/// before the time of its introduction.
 // The bool specifies whether dates should be in the Amete Alem era scheme
 #[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

@@ -40,6 +40,16 @@ 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, as used as an ecclesiastical calendar in Judaism
+/// as of 2025 (using 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

@@ -49,6 +49,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 ecclesiastically 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, an algorithm with 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);
@@ -112,6 +122,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,
@@ -239,6 +257,20 @@ impl Rules for AstronomicalSimulation {
 /// calendar authority.
 ///
 /// This corresponds to the `"islamic-umalqura"` [CLDR calendar](https://unicode.org/reports/tr35/#UnicodeCalendarIdentifier).
+///
+/// # Precise definition and limits
+///
+/// This calendar is intended to match the Umm al-Qura calendar defined and published by the Kingdom of Saudi Arabia,
+/// with the source of truth being government published data/almanacs.
+///
+/// Outside the range 1300 AH (1882-11-12 ISO) to the end of 1600 AH (2174-11-25 ISO) it falls back
+/// to a tabular approximation. These ranges may change in the future.
+///
+/// The precise behavior of this calendar may change in the future if:
+/// - The ground truth in Saudi Arabia changes, either through published government sources or most almanacs
+/// - Future data is published that we wish to incorporate
+/// - We decide to tweak the simplified calculation
+/// - We decide to expand the range where we are handling past dates.
 #[derive(Copy, Clone, Debug, Default)]
 #[non_exhaustive]
 pub struct UmmAlQura;
@@ -315,6 +347,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

@@ -28,6 +28,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 2025.`
+///
+/// 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 happens to be the civil calendar used in Japan from 1873, this calendar extends proleptically
+/// before that.
 #[derive(Clone, Debug, Default)]
 pub struct Japanese {
     eras: DataPayload<CalendarJapaneseModernV1>,