Fix reexport documentation to be clearer when things are reexports (#6372)

Also moves public/stable types TimeZone and TimeZoneVariant out of the
provider module, turning the reexport into the other direction. Even
with `doc(no_inline)`, I'm more comfortable with the provider module
only containing unstable types and reexports of stable types.


Fixes #6240



<!--
Thank you for your pull request to ICU4X!

Reminder: try to use [Conventional
Comments](https://conventionalcomments.org/) to make comments clearer.

Please see
https://github.com/unicode-org/icu4x/blob/main/CONTRIBUTING.md for
general
information on contributing to ICU4X.
-->

Author: Manishearth

components/calendar/src/date.rs

@@ -89,6 +89,8 @@ impl<C> Deref for Ref<'_, C> {
 
 /// A date for a given calendar.
 ///
+/// **The primary definition of this type is in the [`icu_calendar`](docs.rs/icu_calendar) crate. Other ICU4X crates re-export it for convenience.**
+///
 /// This can work with wrappers around [`Calendar`] types,
 /// e.g. `Rc<C>`, via the [`AsCalendar`] trait.
 ///

components/datetime/src/lib.rs

@@ -137,26 +137,14 @@ pub mod preferences {
 }
 
 /// Types that can be fed to [`DateTimeFormatter`]/[`FixedCalendarDateTimeFormatter`].
+///
+/// This module contains re-exports from the [`icu_calendar`] and [`icu_time`] crates.
 pub mod input {
-    /// **This is a reexport of a type in [`icu_calendar`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_calendar::Date;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::zone::UtcOffset;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::DateTime;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::Time;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::TimeZone;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::TimeZoneInfo;
-    /// **This is a reexport of a type in [`icu_time`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use icu_time::ZonedDateTime;
 }

components/decimal/src/lib.rs

@@ -133,18 +133,12 @@ pub mod preferences {
 }
 
 /// Types that can be fed to [`DecimalFormatter`] and their utilities
+///
+/// This module contains re-exports from the [`fixed_decimal`] crate.
 pub mod input {
-    /// **This is a reexport of a type in [`fixed_decimal`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use fixed_decimal::Decimal;
-    /// **This is a reexport of a type in [`fixed_decimal`]**.
-    ///
-    /// This type can be made available with the `"ryu"` Cargo feature.
-    #[doc = "\n"] // prevent autoformatting
     #[cfg(feature = "ryu")]
     pub use fixed_decimal::FloatPrecision;
-    /// **This is a reexport of a type in [`fixed_decimal`]**.
-    #[doc = "\n"] // prevent autoformatting
     pub use fixed_decimal::SignDisplay;
 }
 

components/time/src/provider/mod.rs

@@ -17,14 +17,15 @@
 
 use crate::Time;
 use calendrical_calculations::rata_die::RataDie;
-use core::ops::Deref;
 use icu_calendar::{Date, Iso};
+#[cfg(feature = "datagen")]
 use icu_provider::prelude::*;
-use tinystr::TinyAsciiStr;
 use zerovec::maps::ZeroMapKV;
-use zerovec::ule::{AsULE, ULE};
+use zerovec::ule::AsULE;
 use zerovec::{ZeroMap2d, ZeroSlice, ZeroVec};
 
+pub use crate::zone::ule::TimeZoneVariantULE;
+pub use crate::zone::TimeZone;
 pub mod iana;
 pub mod windows;
 
@@ -62,110 +63,6 @@ pub const MARKERS: &[DataMarkerInfo] = &[
     TimeZoneOffsetsV1::INFO,
 ];
 
-/// A CLDR time zone identity.
-///
-/// This can be created directly from BCP-47 strings, or it can be parsed from IANA IDs.
-///
-/// CLDR uses difference equivalence classes than IANA. For example, `Europe/Oslo` is
-/// an alias to `Europe/Berlin` in IANA (because they agree since 1970), but these are
-/// different identities in CLDR, as we want to be able to say "Norway Time" and
-/// "Germany Time". On the other hand `Europe/Belfast` and `Europe/London` are the same
-/// CLDR identity ("UK Time").
-///
-/// ```
-/// use icu::time::zone::{IanaParser, TimeZone};
-/// use tinystr::tinystr;
-///
-/// let parser = IanaParser::new();
-/// assert_eq!(parser.parse("Europe/Oslo"), TimeZone(tinystr!(8, "noosl")));
-/// assert_eq!(
-///     parser.parse("Europe/Berlin"),
-///     TimeZone(tinystr!(8, "deber"))
-/// );
-/// assert_eq!(
-///     parser.parse("Europe/Belfast"),
-///     TimeZone(tinystr!(8, "gblon"))
-/// );
-/// assert_eq!(
-///     parser.parse("Europe/London"),
-///     TimeZone(tinystr!(8, "gblon"))
-/// );
-/// ```
-#[repr(transparent)]
-#[derive(Debug, Clone, Copy, Eq, Ord, PartialEq, PartialOrd, yoke::Yokeable, ULE, Hash)]
-#[cfg_attr(feature = "datagen", derive(serde::Serialize, databake::Bake))]
-#[cfg_attr(feature = "datagen", databake(path = icu_time::provider))]
-#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
-pub struct TimeZone(pub TinyAsciiStr<8>);
-
-impl TimeZone {
-    /// The synthetic `Etc/Unknown` time zone.
-    ///
-    /// This is the result of parsing unknown zones. It's important that such parsing does not
-    /// fail, as new zones are added all the time, and ICU4X might not be up to date.
-    pub const fn unknown() -> Self {
-        Self(tinystr::tinystr!(8, "unk"))
-    }
-}
-
-impl Deref for TimeZone {
-    type Target = TinyAsciiStr<8>;
-
-    fn deref(&self) -> &Self::Target {
-        &self.0
-    }
-}
-
-impl AsULE for TimeZone {
-    type ULE = Self;
-
-    #[inline]
-    fn to_unaligned(self) -> Self::ULE {
-        self
-    }
-
-    #[inline]
-    fn from_unaligned(unaligned: Self::ULE) -> Self {
-        unaligned
-    }
-}
-
-impl<'a> zerovec::maps::ZeroMapKV<'a> for TimeZone {
-    type Container = ZeroVec<'a, TimeZone>;
-    type Slice = ZeroSlice<TimeZone>;
-    type GetType = TimeZone;
-    type OwnedType = TimeZone;
-}
-
-/// A time zone variant, such as Standard Time, or Daylight/Summer Time.
-///
-/// This should not generally be constructed by client code. Instead, use
-/// * [`TimeZoneVariant::from_rearguard_isdst`]
-/// * [`TimeZoneInfo::infer_zone_variant`](crate::TimeZoneInfo::infer_zone_variant)
-#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
-#[zerovec::make_ule(TimeZoneVariantULE)]
-#[repr(u8)]
-#[cfg_attr(feature = "datagen", derive(serde::Serialize, databake::Bake))]
-#[cfg_attr(feature = "datagen", databake(path = icu_time))]
-#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
-#[non_exhaustive]
-pub enum TimeZoneVariant {
-    /// The variant corresponding to `"standard"` in CLDR.
-    ///
-    /// The semantics vary from time zone to time zone. The time zone display
-    /// name of this variant may or may not be called "Standard Time".
-    ///
-    /// This is the variant with the lower UTC offset.
-    Standard = 0,
-    /// The variant corresponding to `"daylight"` in CLDR.
-    ///
-    /// The semantics vary from time zone to time zone. The time zone display
-    /// name of this variant may or may not be called "Daylight Time".
-    ///
-    /// This is the variant with the higher UTC offset.
-    Daylight = 1,
-}
-
 /// Storage type for storing UTC offsets as eights of an hour.
 pub type EighthsOfHourOffset = i8;
 /// Storage type for storing `(Date<Iso>, Time)`.

components/time/src/types.rs

@@ -118,6 +118,8 @@ dt_unit!(
 
 /// A representation of a time in hours, minutes, seconds, and nanoseconds
 ///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
+///
 /// This type supports the range [00:00:00.000000000, 23:59:60.999999999].
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
@@ -168,6 +170,8 @@ impl Time {
 }
 
 /// A date and time for a given calendar.
+///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
 #[derive(Debug, PartialEq, Eq)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct DateTime<A: AsCalendar> {
@@ -178,6 +182,8 @@ pub struct DateTime<A: AsCalendar> {
 }
 
 /// A date and time for a given calendar, local to a specified time zone.
+///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
 #[derive(Debug, PartialEq, Eq)]
 #[allow(clippy::exhaustive_structs)] // this type is stable
 pub struct ZonedDateTime<A: AsCalendar, Z> {

components/time/src/zone/mod.rs

@@ -88,7 +88,6 @@ mod offset;
 pub mod windows;
 
 #[doc(inline)]
-pub use crate::provider::{TimeZone, TimeZoneVariant};
 pub use offset::InvalidOffsetError;
 pub use offset::UtcOffset;
 pub use offset::VariantOffsets;
@@ -102,7 +101,12 @@ pub use windows::WindowsParser;
 
 use crate::{scaffold::IntoOption, Time};
 use core::fmt;
+use core::ops::Deref;
 use icu_calendar::{Date, Iso};
+use icu_provider::prelude::yoke;
+use tinystr::TinyAsciiStr;
+use zerovec::ule::{AsULE, ULE};
+use zerovec::{ZeroSlice, ZeroVec};
 
 /// Time zone data model choices.
 pub mod models {
@@ -158,7 +162,120 @@ pub mod models {
     }
 }
 
+/// A CLDR time zone identity.
+///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
+///
+/// This can be created directly from BCP-47 strings, or it can be parsed from IANA IDs.
+///
+/// CLDR uses difference equivalence classes than IANA. For example, `Europe/Oslo` is
+/// an alias to `Europe/Berlin` in IANA (because they agree since 1970), but these are
+/// different identities in CLDR, as we want to be able to say "Norway Time" and
+/// "Germany Time". On the other hand `Europe/Belfast` and `Europe/London` are the same
+/// CLDR identity ("UK Time").
+///
+/// ```
+/// use icu::time::zone::{IanaParser, TimeZone};
+/// use tinystr::tinystr;
+///
+/// let parser = IanaParser::new();
+/// assert_eq!(parser.parse("Europe/Oslo"), TimeZone(tinystr!(8, "noosl")));
+/// assert_eq!(
+///     parser.parse("Europe/Berlin"),
+///     TimeZone(tinystr!(8, "deber"))
+/// );
+/// assert_eq!(
+///     parser.parse("Europe/Belfast"),
+///     TimeZone(tinystr!(8, "gblon"))
+/// );
+/// assert_eq!(
+///     parser.parse("Europe/London"),
+///     TimeZone(tinystr!(8, "gblon"))
+/// );
+/// ```
+#[repr(transparent)]
+#[derive(Debug, Clone, Copy, Eq, Ord, PartialEq, PartialOrd, yoke::Yokeable, ULE, Hash)]
+#[cfg_attr(feature = "datagen", derive(serde::Serialize, databake::Bake))]
+#[cfg_attr(feature = "datagen", databake(path = icu_time))]
+#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
+#[allow(clippy::exhaustive_structs)] // This is a stable newtype
+pub struct TimeZone(pub TinyAsciiStr<8>);
+
+impl TimeZone {
+    /// The synthetic `Etc/Unknown` time zone.
+    ///
+    /// This is the result of parsing unknown zones. It's important that such parsing does not
+    /// fail, as new zones are added all the time, and ICU4X might not be up to date.
+    pub const fn unknown() -> Self {
+        Self(tinystr::tinystr!(8, "unk"))
+    }
+}
+
+/// This module exists so we can cleanly reexport TimeZoneVariantULE from the provider module, whilst retaining a public stable TimeZoneVariant type.
+pub(crate) mod ule {
+    /// A time zone variant, such as Standard Time, or Daylight/Summer Time.
+    ///
+    /// This should not generally be constructed by client code. Instead, use
+    /// * [`TimeZoneVariant::from_rearguard_isdst`]
+    /// * [`TimeZoneInfo::infer_zone_variant`](crate::TimeZoneInfo::infer_zone_variant)
+    #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
+    #[zerovec::make_ule(TimeZoneVariantULE)]
+    #[repr(u8)]
+    #[cfg_attr(feature = "datagen", derive(serde::Serialize, databake::Bake))]
+    #[cfg_attr(feature = "datagen", databake(path = icu_time))]
+    #[cfg_attr(feature = "serde", derive(serde::Deserialize))]
+    #[non_exhaustive]
+    pub enum TimeZoneVariant {
+        /// The variant corresponding to `"standard"` in CLDR.
+        ///
+        /// The semantics vary from time zone to time zone. The time zone display
+        /// name of this variant may or may not be called "Standard Time".
+        ///
+        /// This is the variant with the lower UTC offset.
+        Standard = 0,
+        /// The variant corresponding to `"daylight"` in CLDR.
+        ///
+        /// The semantics vary from time zone to time zone. The time zone display
+        /// name of this variant may or may not be called "Daylight Time".
+        ///
+        /// This is the variant with the higher UTC offset.
+        Daylight = 1,
+    }
+}
+pub use ule::TimeZoneVariant;
+
+impl Deref for TimeZone {
+    type Target = TinyAsciiStr<8>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl AsULE for TimeZone {
+    type ULE = Self;
+
+    #[inline]
+    fn to_unaligned(self) -> Self::ULE {
+        self
+    }
+
+    #[inline]
+    fn from_unaligned(unaligned: Self::ULE) -> Self {
+        unaligned
+    }
+}
+
+impl<'a> zerovec::maps::ZeroMapKV<'a> for TimeZone {
+    type Container = ZeroVec<'a, TimeZone>;
+    type Slice = ZeroSlice<TimeZone>;
+    type GetType = TimeZone;
+    type OwnedType = TimeZone;
+}
+
 /// A utility type that can hold time zone information.
+///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
 #[derive(Debug, PartialEq, Eq)]
 #[allow(clippy::exhaustive_structs)] // these four fields fully cover the needs of UTS 35
 pub struct TimeZoneInfo<Model: models::TimeZoneModel> {

components/time/src/zone/offset.rs

@@ -19,6 +19,8 @@ use zerovec::ZeroMap2d;
 pub struct InvalidOffsetError;
 
 /// An offset from Coordinated Universal Time (UTC)
+///
+/// **The primary definition of this type is in the [`icu_time`](docs.rs/icu_time) crate. Other ICU4X crates re-export it for convenience.**
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Default, PartialOrd, Ord)]
 pub struct UtcOffset(i32);
 

utils/fixed_decimal/src/rounding.rs

@@ -141,12 +141,14 @@ pub enum RoundingIncrement {
     MultiplesOf25,
 }
 
-/// Specifies the precision of a floating point value when constructing a FixedDecimal.
+/// Specifies the precision of a floating point value when constructing a Decimal.
 ///
-/// IEEE 754 is a representation of a point on the number line. On the other hand, FixedDecimal
+/// **The primary definition of this type is in the [`fixed_decimal`](docs.rs/fixed_decimal) crate. Other ICU4X crates re-export it for convenience.**
+///
+/// IEEE 754 is a representation of a point on the number line. On the other hand, Decimal
 /// specifies not only the point on the number line but also the precision of the number to a
 /// specific power of 10. This enum augments a floating-point value with the additional
-/// information required by FixedDecimal.
+/// information required by Decimal.
 #[non_exhaustive]
 #[cfg(feature = "ryu")]
 #[derive(Debug, Clone, Copy)]
@@ -168,7 +170,7 @@ pub enum FloatPrecision {
 
     /// Specify that the floating point number is precise to the maximum representable by IEEE.
     ///
-    /// This results in a FixedDecimal having enough digits to recover the original floating point
+    /// This results in a Decimal having enough digits to recover the original floating point
     /// value, with no trailing zeros.
     RoundTrip,
 }