Fix documentation about standard/daylight time zone variants (unicode…

…-org#4921)

Fixes unicode-org#4919

components/timezone/src/lib.rs

@@ -11,7 +11,7 @@
 //! 1. The offset from GMT
 //! 2. The time zone ID
 //! 3. The metazone ID
-//! 4. The zone variant (standard or daylight time)
+//! 4. The zone variant, representing concepts such as Standard, Summer, Daylight, and Ramadan time
 //!
 //! ## GMT Offset
 //!
@@ -58,10 +58,11 @@
 //! ## Zone Variant
 //!
 //! Many metazones use different names and offsets in the summer than in the winter. In ICU4X,
-//! this is called the _zone variant_. There are two zone variants:
+//! this is called the _zone variant_.
 //!
-//! 1. `"dt"` = daylight or summer time
-//! 2. `"st"` = standard or winter time
+//! CLDR has two zone variants, named `"standard"` and `"daylight"`. However, the mapping of these
+//! variants to specific observed offsets varies from time zone to time zone, and they may not
+//! consistently represent winter versus summer time.
 //!
 //! Note: It is optional (not required) to set the zone variant when constructing a
 //! [`CustomTimeZone`]. Therefore, the list of possible variants does not include a generic variant

components/timezone/src/types.rs

@@ -178,7 +178,9 @@ impl FromStr for GmtOffset {
     }
 }
 
-/// A time zone variant: currently either daylight time or standard time.
+/// A time zone variant, representing the currently observed relative offset.
+/// The semantics vary from time zone to time zone and could represent concepts
+/// such as Standard time, Daylight time, Summer time, or Ramadan time.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash, ULE)]
 #[repr(transparent)]
 #[cfg_attr(feature = "datagen", derive(serde::Serialize, databake::Bake), databake(path = icu_timezone))]
@@ -195,15 +197,17 @@ impl FromStr for ZoneVariant {
 }
 
 impl ZoneVariant {
-    /// Return the standard time `ZoneVariant`.
+    /// Returns the variant corresponding to `"standard"` in CLDR.
     ///
-    /// Corresponds to the `"standard"` variant string 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".
     pub const fn standard() -> Self {
         Self(tinystr!(2, "st"))
     }
-    /// Return the daylight time `ZoneVariant`
+    /// Returns the variant corresponding to `"daylight"` in CLDR.
     ///
-    /// Corresponds to the `"daylight"` variant string 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".
     pub const fn daylight() -> Self {
         Self(tinystr!(2, "dt"))
     }

ffi/capi/src/timezone.rs

@@ -273,14 +273,16 @@ pub mod ffi {
             Ok(())
         }
 
-        /// Sets the `zone_variant` field to standard time.
+        /// Sets the `zone_variant` field to "standard" time, which may or may
+        /// not correspond to a display name with "Standard" in its name.
         #[diplomat::rust_link(icu::timezone::ZoneVariant::standard, FnInStruct)]
         #[diplomat::rust_link(icu::timezone::CustomTimeZone::zone_variant, StructField, compact)]
         pub fn set_standard_time(&mut self) {
             self.0.zone_variant = Some(ZoneVariant::standard())
         }
 
-        /// Sets the `zone_variant` field to daylight time.
+        /// Sets the `zone_variant` field to "daylight" time, which may or may
+        /// not correspond to a display name with "Daylight" in its name.
         #[diplomat::rust_link(icu::timezone::ZoneVariant::daylight, FnInStruct)]
         #[diplomat::rust_link(icu::timezone::CustomTimeZone::zone_variant, StructField, compact)]
         pub fn set_daylight_time(&mut self) {