Skip to content

Commit ac39015

Browse files
robertbastianrobertbastian
committed
Improving icu_locid_transform docs (#4099)
1 parent a766bbd commit ac39015

File tree

9 files changed

+53
-33
lines changed

9 files changed

+53
-33
lines changed

‎components/locid_transform/src/canonicalizer.rs‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,7 @@ use icu_locid::{
2020
use icu_provider::prelude::*;
2121
use tinystr::TinyAsciiStr;
2222

23-
/// The LocaleCanonicalizer provides methods to canonicalize Locales and
24-
/// LanguageIdentifiers based upon [`CLDR`] data.
25-
///
26-
/// It currently supports locale canonicalization based upon the canonicalization
27-
/// algorithm from [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`].
23+
/// Implements the algorithm defined in *[UTS #35: Annex C, LocaleId Canonicalization]*.
2824
///
2925
/// # Examples
3026
///
@@ -39,9 +35,7 @@ use tinystr::TinyAsciiStr;
3935
/// assert_eq!(locale, "ja-Latn-alalc97-fonipa".parse().unwrap());
4036
/// ```
4137
///
42-
/// [`ICU4X`]: ../icu/index.html
43-
/// [`CLDR`]: http://cldr.unicode.org/
44-
/// [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization,
38+
/// [UTS #35: Annex C, LocaleId Canonicalization]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization
4539
#[derive(Debug)]
4640
pub struct LocaleCanonicalizer {
4741
/// Data to support canonicalization.

‎components/locid_transform/src/directionality.rs‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,7 @@ pub enum Direction {
2020
RightToLeft,
2121
}
2222

23-
/// The `LocaleDirectionality` provides methods to determine the direction of a locale based
24-
/// on [`CLDR`] data.
23+
/// Provides methods to determine the direction of a locale.
2524
///
2625
/// # Examples
2726
///
@@ -33,8 +32,6 @@ pub enum Direction {
3332
///
3433
/// assert_eq!(ld.get(&locale!("en")), Some(Direction::LeftToRight));
3534
/// ```
36-
///
37-
/// [`CLDR`]: http://cldr.unicode.org/
3835
#[derive(Debug)]
3936
pub struct LocaleDirectionality {
4037
script_direction: DataPayload<ScriptDirectionV1Marker>,

‎components/locid_transform/src/expander.rs‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,8 @@ use icu_provider::prelude::*;
1111

1212
use crate::TransformResult;
1313

14-
/// LocaleExpander supports the `minimize` and `maximize` likely subtags
15-
/// algorithms as described in [`UTS #35: Unicode LDML 3. Likely Subtags`].
16-
///
17-
/// The maximize method potentially updates a passed in locale in place
18-
/// depending up the results of running the 'Add Likely Subtags' algorithm
19-
/// from [`UTS #35: Unicode LDML 3. Likely Subtags`].
20-
///
21-
/// This minimize method returns a new Locale that is the result of running the
22-
/// 'Remove Likely Subtags' algorithm from [`UTS #35: Unicode LDML 3. Likely Subtags`].
14+
/// Implements the *Add Likely Subtags* and *Remove Likely Subtags*
15+
/// algorithms as defined in *[UTS #35: Likely Subtags]*.
2316
///
2417
/// # Examples
2518
///
@@ -71,8 +64,7 @@ use crate::TransformResult;
7164
/// assert_eq!(locale, locale!("atj-Latn-CA"));
7265
/// ```
7366
///
74-
/// [`CLDR`]: http://cldr.unicode.org/
75-
/// [`UTS #35: Unicode LDML 3. Likely Subtags`]: https://www.unicode.org/reports/tr35/#Likely_Subtags.
67+
/// [UTS #35: Likely Subtags]: https://www.unicode.org/reports/tr35/#Likely_Subtags
7668
#[derive(Debug, Clone)]
7769
pub struct LocaleExpander {
7870
likely_subtags_l: DataPayload<LikelySubtagsForLanguageV1Marker>,

‎components/locid_transform/src/fallback/mod.rs‎

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
//!
1515
//! ```
1616
//! use icu_locid::locale;
17-
//! use icu_locid_transform::fallback::LocaleFallbacker;
17+
//! use icu_locid_transform::LocaleFallbacker;
1818
//!
1919
//! // Set up a LocaleFallbacker with data.
2020
//! let fallbacker = LocaleFallbacker::new();
@@ -49,9 +49,44 @@ pub use icu_provider::fallback::*;
4949

5050
mod algorithms;
5151

52-
/// Entry type for locale fallbacking.
52+
/// Implements the algorithm defined in *[UTS #35: Locale Inheritance and Matching]*.
5353
///
54-
/// See the module-level documentation for an example.
54+
/// Note that this implementation performs some additional steps compared to the *UTS #35*
55+
/// algorithm, see *[the design doc]* for a detailed description, and [#2243](
56+
/// https://github.com/unicode-org/icu4x/issues/2243) to track aligment with *UTS #35*.
57+
///
58+
/// # Examples
59+
///
60+
/// ```
61+
/// use icu_locid::locale;
62+
/// use icu_locid_transform::fallback::LocaleFallbacker;
63+
///
64+
/// // Set up a LocaleFallbacker with data.
65+
/// let fallbacker = LocaleFallbacker::new();
66+
///
67+
/// // Create a LocaleFallbackerIterator with a default configuration.
68+
/// // By default, uses language priority with no additional extension keywords.
69+
/// let mut fallback_iterator = fallbacker
70+
/// .for_config(Default::default())
71+
/// .fallback_for(locale!("hi-Latn-IN").into());
72+
///
73+
/// // Run the algorithm and check the results.
74+
/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn-IN").into());
75+
/// fallback_iterator.step();
76+
/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn").into());
77+
/// fallback_iterator.step();
78+
/// assert_eq!(fallback_iterator.get(), &locale!("en-IN").into());
79+
/// fallback_iterator.step();
80+
/// assert_eq!(fallback_iterator.get(), &locale!("en-001").into());
81+
/// fallback_iterator.step();
82+
/// assert_eq!(fallback_iterator.get(), &locale!("en").into());
83+
/// fallback_iterator.step();
84+
/// assert_eq!(fallback_iterator.get(), &locale!("und").into());
85+
/// ```
86+
///
87+
/// [UTS #35: Locale Inheritance and Matching]: https://www.unicode.org/reports/tr35/#Locale_Inheritance
88+
/// [the design doc]: https://docs.google.com/document/d/1Mp7EUyl-sFh_HZYgyeVwj88vJGpCBIWxzlCwGgLCDwM/edit
89+
#[doc(hidden)]
5590
#[derive(Debug, Clone, PartialEq)]
5691
pub struct LocaleFallbacker {
5792
likely_subtags: DataPayload<LocaleFallbackLikelySubtagsV1Marker>,

‎components/locid_transform/src/lib.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,8 @@ pub use canonicalizer::LocaleCanonicalizer;
9999
pub use directionality::{Direction, LocaleDirectionality};
100100
pub use error::LocaleTransformError;
101101
pub use expander::LocaleExpander;
102+
#[doc(inline)]
103+
pub use fallback::LocaleFallbacker;
102104

103105
/// Used to track the result of a transformation operation that potentially modifies its argument in place.
104106
#[derive(Debug, PartialEq)]

‎ffi/diplomat/src/fallbacker.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ pub mod ffi {
88
use icu_locid_transform::fallback::LocaleFallbackConfig;
99
use icu_locid_transform::fallback::LocaleFallbackIterator;
1010
use icu_locid_transform::fallback::LocaleFallbackPriority;
11-
use icu_locid_transform::fallback::LocaleFallbacker;
1211
use icu_locid_transform::fallback::LocaleFallbackerWithConfig;
12+
use icu_locid_transform::LocaleFallbacker;
1313

1414
use crate::{
1515
errors::ffi::ICU4XError, locale::ffi::ICU4XLocale, provider::ffi::ICU4XDataProvider,

‎provider/adapters/src/fallback/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ impl<P> LocaleFallbackProvider<P> {
126126
///
127127
/// ```
128128
/// use icu_locid::locale;
129-
/// use icu_locid_transform::fallback::LocaleFallbacker;
129+
/// use icu_locid_transform::LocaleFallbacker;
130130
/// use icu_provider::hello_world::*;
131131
/// use icu_provider::prelude::*;
132132
/// use icu_provider_adapters::fallback::LocaleFallbackProvider;

‎provider/core/src/fallback.rs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ pub struct LocaleFallbackConfig {
6565
/// use icu_locid::locale;
6666
/// use icu_locid_transform::fallback::LocaleFallbackConfig;
6767
/// use icu_locid_transform::fallback::LocaleFallbackPriority;
68-
/// use icu_locid_transform::fallback::LocaleFallbacker;
68+
/// use icu_locid_transform::LocaleFallbacker;
6969
///
7070
/// // Set up the fallback iterator.
7171
/// let fallbacker = LocaleFallbacker::new();
@@ -93,7 +93,7 @@ pub struct LocaleFallbackConfig {
9393
/// use icu_locid::locale;
9494
/// use icu_locid_transform::fallback::LocaleFallbackConfig;
9595
/// use icu_locid_transform::fallback::LocaleFallbackPriority;
96-
/// use icu_locid_transform::fallback::LocaleFallbacker;
96+
/// use icu_locid_transform::LocaleFallbacker;
9797
///
9898
/// // Set up the fallback iterator.
9999
/// let fallbacker = LocaleFallbacker::new();
@@ -122,7 +122,7 @@ pub struct LocaleFallbackConfig {
122122
/// ```
123123
/// use icu_locid::locale;
124124
/// use icu_locid_transform::fallback::LocaleFallbackConfig;
125-
/// use icu_locid_transform::fallback::LocaleFallbacker;
125+
/// use icu_locid_transform::LocaleFallbacker;
126126
///
127127
/// // Set up the fallback iterator.
128128
/// let fallbacker = LocaleFallbacker::new();
@@ -159,7 +159,7 @@ pub struct LocaleFallbackConfig {
159159
/// use icu_locid_transform::fallback::LocaleFallbackConfig;
160160
/// use icu_locid_transform::fallback::LocaleFallbackPriority;
161161
/// use icu_locid_transform::fallback::LocaleFallbackSupplement;
162-
/// use icu_locid_transform::fallback::LocaleFallbacker;
162+
/// use icu_locid_transform::LocaleFallbacker;
163163
///
164164
/// // Set up the fallback iterator.
165165
/// let fallbacker = LocaleFallbacker::new();

‎provider/datagen/src/driver.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ use crate::FallbackMode;
77
use icu_locid::extensions::unicode::key;
88
use icu_locid::LanguageIdentifier;
99
use icu_locid_transform::fallback::LocaleFallbackIterator;
10-
use icu_locid_transform::fallback::LocaleFallbacker;
10+
use icu_locid_transform::LocaleFallbacker;
1111
use icu_provider::datagen::*;
1212
use icu_provider::prelude::*;
1313
use once_cell::sync::Lazy;

0 commit comments

Comments
 (0)