From 85b5ad9b43fc21872fb76f7ac96b5c02670cc522 Mon Sep 17 00:00:00 2001 From: "Shane F. Carr" Date: Tue, 21 May 2024 09:22:20 -0700 Subject: [PATCH] Fix documentation about standard/daylight time zone variants (#4921) Fixes #4919 --- components/timezone/README.md | 9 +++++---- components/timezone/src/lib.rs | 9 +++++---- components/timezone/src/types.rs | 14 +++++++++----- ffi/capi/bindings/cpp/ICU4XCustomTimeZone.hpp | 6 ++++-- ffi/capi/bindings/dart/CustomTimeZone.g.dart | 6 ++++-- ffi/capi/bindings/js/ICU4XCustomTimeZone.d.ts | 4 ++-- ffi/capi/src/timezone.rs | 6 ++++-- 7 files changed, 33 insertions(+), 21 deletions(-) diff --git a/components/timezone/README.md b/components/timezone/README.md index 2dd844c10ed..e0d85f7c365 100644 --- a/components/timezone/README.md +++ b/components/timezone/README.md @@ -11,7 +11,7 @@ In ICU4X, a [formattable time zone](CustomTimeZone) consists of four different f 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 @@ and module name, where "timezone" is used with no separators. See ### 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 diff --git a/components/timezone/src/lib.rs b/components/timezone/src/lib.rs index 24d2be993b3..adfa01b4d8d 100644 --- a/components/timezone/src/lib.rs +++ b/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 diff --git a/components/timezone/src/types.rs b/components/timezone/src/types.rs index 1c0d167f451..f25dfbae1c9 100644 --- a/components/timezone/src/types.rs +++ b/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")) } diff --git a/ffi/capi/bindings/cpp/ICU4XCustomTimeZone.hpp b/ffi/capi/bindings/cpp/ICU4XCustomTimeZone.hpp index 7b3b375da1e..f2491dcfaf7 100644 --- a/ffi/capi/bindings/cpp/ICU4XCustomTimeZone.hpp +++ b/ffi/capi/bindings/cpp/ICU4XCustomTimeZone.hpp @@ -257,7 +257,8 @@ class ICU4XCustomTimeZone { diplomat::result zone_variant() const; /** - * 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. * * See the [Rust documentation for `standard`](https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.standard) for more information. * @@ -266,7 +267,8 @@ class ICU4XCustomTimeZone { void set_standard_time(); /** - * 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. * * See the [Rust documentation for `daylight`](https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.daylight) for more information. * diff --git a/ffi/capi/bindings/dart/CustomTimeZone.g.dart b/ffi/capi/bindings/dart/CustomTimeZone.g.dart index 16cf6355bdb..7ed9a0397f0 100644 --- a/ffi/capi/bindings/dart/CustomTimeZone.g.dart +++ b/ffi/capi/bindings/dart/CustomTimeZone.g.dart @@ -317,7 +317,8 @@ final class CustomTimeZone implements ffi.Finalizable { return writeable.finalize(); } - /// 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. /// /// See the [Rust documentation for `standard`](https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.standard) for more information. /// @@ -326,7 +327,8 @@ final class CustomTimeZone implements ffi.Finalizable { _ICU4XCustomTimeZone_set_standard_time(_ffi); } - /// 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. /// /// See the [Rust documentation for `daylight`](https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.daylight) for more information. /// diff --git a/ffi/capi/bindings/js/ICU4XCustomTimeZone.d.ts b/ffi/capi/bindings/js/ICU4XCustomTimeZone.d.ts index 290f7881ad3..8e37885ccb3 100644 --- a/ffi/capi/bindings/js/ICU4XCustomTimeZone.d.ts +++ b/ffi/capi/bindings/js/ICU4XCustomTimeZone.d.ts @@ -237,7 +237,7 @@ export class ICU4XCustomTimeZone { /** - * 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. * See the {@link https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.standard Rust documentation for `standard`} for more information. @@ -247,7 +247,7 @@ export class ICU4XCustomTimeZone { /** - * 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. * See the {@link https://docs.rs/icu/latest/icu/timezone/struct.ZoneVariant.html#method.daylight Rust documentation for `daylight`} for more information. diff --git a/ffi/capi/src/timezone.rs b/ffi/capi/src/timezone.rs index cf990dca05b..2b83ae7d2da 100644 --- a/ffi/capi/src/timezone.rs +++ b/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) {