docs

Author: robertbastian

components/calendar/src/cal/buddhist.rs

@@ -74,9 +74,10 @@ impl GregorianYears for BuddhistEra {
 }
 
 impl Date<Buddhist> {
-    /// Construct a new Buddhist Date.
+    /// Construct a new Buddhist [`Date`].
     ///
-    /// Years are specified as BE years.
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::Date;

components/calendar/src/cal/coptic.rs

@@ -234,7 +234,10 @@ impl Calendar for Coptic {
 }
 
 impl Date<Coptic> {
-    /// Construct new Coptic Date.
+    /// Construct new Coptic [`Date`].
+    ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::Date;

components/calendar/src/cal/east_asian_traditional.rs

@@ -489,6 +489,9 @@ impl Rules for Korea {
 impl<A: AsCalendar<Calendar = KoreanTraditional>> Date<A> {
     /// This method uses an ordinal month, which is probably not what you want.
     ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
+    ///
     /// Use [`Date::try_new_from_codes`]
     #[deprecated(since = "2.1.0", note = "use `Date::try_new_from_codes`")]
     pub fn try_new_dangi_with_calendar(
@@ -797,6 +800,9 @@ impl<R: Rules> Calendar for EastAsianTraditional<R> {
 impl<A: AsCalendar<Calendar = ChineseTraditional>> Date<A> {
     /// This method uses an ordinal month, which is probably not what you want.
     ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
+    ///
     /// Use [`Date::try_new_from_codes`]
     #[deprecated(since = "2.1.0", note = "use `Date::try_new_from_codes`")]
     pub fn try_new_chinese_with_calendar(

components/calendar/src/cal/ethiopian.rs

@@ -272,7 +272,12 @@ impl Ethiopian {
 }
 
 impl Date<Ethiopian> {
-    /// Construct new Ethiopian Date.
+    /// Construct new Ethiopian [`Date`].
+    ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
+    ///
+    /// Years are interpreted according to the provided `era_style`.
     ///
     /// ```rust
     /// use icu::calendar::cal::EthiopianEraStyle;

components/calendar/src/cal/gregorian.rs

@@ -118,9 +118,10 @@ impl GregorianYears for CeBce {
 pub struct Gregorian;
 
 impl Date<Gregorian> {
-    /// Construct a new Gregorian Date.
+    /// Construct a new Gregorian [`Date`].
     ///
-    /// Years are specified as ISO years.
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::Date;

components/calendar/src/cal/hebrew.rs

@@ -357,6 +357,9 @@ impl Calendar for Hebrew {
 impl Date<Hebrew> {
     /// This method uses an ordinal month, which is probably not what you want.
     ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
+    ///
     /// Use [`Date::try_new_from_codes`]
     #[deprecated(since = "2.1.0", note = "use `Date::try_new_from_codes`")]
     pub fn try_new_hebrew(

components/calendar/src/cal/hijri.rs

@@ -1040,7 +1040,10 @@ impl<R: Rules> Calendar for Hijri<R> {
 }
 
 impl<A: AsCalendar<Calendar = Hijri<R>>, R: Rules> Date<A> {
-    /// Construct new Hijri Date.
+    /// Construct new Hijri [`Date`].
+    ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::cal::Hijri;

components/calendar/src/cal/indian.rs

@@ -283,7 +283,10 @@ impl Indian {
 }
 
 impl Date<Indian> {
-    /// Construct new Indian Date, with year provided in the Śaka era.
+    /// Construct new Indian [`Date`].
+    ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::Date;

components/calendar/src/cal/iso.rs

@@ -55,7 +55,10 @@ impl GregorianYears for IsoEra {
 }
 
 impl Date<Iso> {
-    /// Construct a new ISO date from integers.
+    /// Construct a new ISO [`Date`].
+    ///
+    /// Years are arithmetic, meaning there is a year 0 preceded by negative years, with a
+    /// valid range of `-1,000,000..=1,000,000`.
     ///
     /// ```rust
     /// use icu::calendar::Date;

components/calendar/src/cal/japanese.rs

@@ -298,14 +298,16 @@ impl_with_abstract_gregorian!(
 );
 
 impl Date<Japanese> {
-    /// Construct a new Japanese Date.
+    /// Construct a new Japanese [`Date`].
     ///
     /// Years are specified in the era provided, and must be in range for Japanese
     /// eras (e.g. dates past April 30 Heisei 31 must be in Reiwa; "Jun 5 Heisei 31" and "Jan 1 Heisei 32"
     /// will not be adjusted to being in Reiwa 1 and 2 respectively)
     ///
     /// However, dates may always be specified in "bce" or "ce" and they will be adjusted as necessary.
     ///
+    /// This function accepts years that correspond to Gregorian years in the range `-1,000,000..=1,000,000`.
+    ///
     /// ```rust
     /// use icu::calendar::cal::Japanese;
     /// use icu::calendar::{Date, Ref};
@@ -365,6 +367,8 @@ impl Date<JapaneseExtended> {
     ///
     /// However, dates may always be specified in "bce" or "ce" and they will be adjusted as necessary.
     ///
+    /// This function accepts years that correspond to Gregorian years in the range `-1,000,000..=1,000,000`.
+    ///
     /// ```rust
     /// use icu::calendar::cal::JapaneseExtended;
     /// use icu::calendar::{Date, Ref};