Improving icu_locid_transform docs (#4099)

components/locid_transform/src/canonicalizer.rs

@@ -20,11 +20,7 @@ use icu_locid::{
 use icu_provider::prelude::*;
 use tinystr::TinyAsciiStr;
 
-/// The LocaleCanonicalizer provides methods to canonicalize Locales and
-/// LanguageIdentifiers based upon [`CLDR`] data.
-///
-/// It currently supports locale canonicalization based upon the canonicalization
-/// algorithm from [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`].
+/// Implements the algorithm defined in *[UTS #35: Annex C, LocaleId Canonicalization]*.
 ///
 /// # Examples
 ///
@@ -39,9 +35,7 @@ use tinystr::TinyAsciiStr;
 /// assert_eq!(locale, "ja-Latn-alalc97-fonipa".parse().unwrap());
 /// ```
 ///
-/// [`ICU4X`]: ../icu/index.html
-/// [`CLDR`]: http://cldr.unicode.org/
-/// [`UTS #35: Unicode LDML 3. LocaleId Canonicalization`]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization,
+/// [UTS #35: Annex C, LocaleId Canonicalization]: http://unicode.org/reports/tr35/#LocaleId_Canonicalization
 #[derive(Debug)]
 pub struct LocaleCanonicalizer {
     /// Data to support canonicalization.

components/locid_transform/src/directionality.rs

@@ -20,8 +20,7 @@ pub enum Direction {
     RightToLeft,
 }
 
-/// The `LocaleDirectionality` provides methods to determine the direction of a locale based
-/// on [`CLDR`] data.
+/// Provides methods to determine the direction of a locale.
 ///
 /// # Examples
 ///
@@ -33,8 +32,6 @@ pub enum Direction {
 ///
 /// assert_eq!(ld.get(&locale!("en")), Some(Direction::LeftToRight));
 /// ```
-///
-/// [`CLDR`]: http://cldr.unicode.org/
 #[derive(Debug)]
 pub struct LocaleDirectionality {
     script_direction: DataPayload<ScriptDirectionV1Marker>,

components/locid_transform/src/expander.rs

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

components/locid_transform/src/fallback/mod.rs

@@ -14,7 +14,7 @@
 //!
 //! ```
 //! use icu_locid::locale;
-//! use icu_locid_transform::fallback::LocaleFallbacker;
+//! use icu_locid_transform::LocaleFallbacker;
 //!
 //! // Set up a LocaleFallbacker with data.
 //! let fallbacker = LocaleFallbacker::new();
@@ -49,9 +49,44 @@ pub use icu_provider::fallback::*;
 
 mod algorithms;
 
-/// Entry type for locale fallbacking.
+/// Implements the algorithm defined in *[UTS #35: Locale Inheritance and Matching]*.
 ///
-/// See the module-level documentation for an example.
+/// Note that this implementation performs some additional steps compared to the *UTS #35*
+/// algorithm, see *[the design doc]* for a detailed description, and [#2243](
+/// https://github.com/unicode-org/icu4x/issues/2243) to track aligment with *UTS #35*.
+///
+/// # Examples
+///
+/// ```
+/// use icu_locid::locale;
+/// use icu_locid_transform::fallback::LocaleFallbacker;
+///
+/// // Set up a LocaleFallbacker with data.
+/// let fallbacker = LocaleFallbacker::new();
+///
+/// // Create a LocaleFallbackerIterator with a default configuration.
+/// // By default, uses language priority with no additional extension keywords.
+/// let mut fallback_iterator = fallbacker
+///     .for_config(Default::default())
+///     .fallback_for(locale!("hi-Latn-IN").into());
+///
+/// // Run the algorithm and check the results.
+/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn-IN").into());
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get(), &locale!("hi-Latn").into());
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get(), &locale!("en-IN").into());
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get(), &locale!("en-001").into());
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get(), &locale!("en").into());
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get(), &locale!("und").into());
+/// ```
+///
+/// [UTS #35: Locale Inheritance and Matching]: https://www.unicode.org/reports/tr35/#Locale_Inheritance
+/// [the design doc]: https://docs.google.com/document/d/1Mp7EUyl-sFh_HZYgyeVwj88vJGpCBIWxzlCwGgLCDwM/edit
+#[doc(hidden)]
 #[derive(Debug, Clone, PartialEq)]
 pub struct LocaleFallbacker {
     likely_subtags: DataPayload<LocaleFallbackLikelySubtagsV1Marker>,

components/locid_transform/src/lib.rs

@@ -99,6 +99,8 @@ pub use canonicalizer::LocaleCanonicalizer;
 pub use directionality::{Direction, LocaleDirectionality};
 pub use error::LocaleTransformError;
 pub use expander::LocaleExpander;
+#[doc(inline)]
+pub use fallback::LocaleFallbacker;
 
 /// Used to track the result of a transformation operation that potentially modifies its argument in place.
 #[derive(Debug, PartialEq)]

ffi/diplomat/src/fallbacker.rs

@@ -8,8 +8,8 @@ pub mod ffi {
     use icu_locid_transform::fallback::LocaleFallbackConfig;
     use icu_locid_transform::fallback::LocaleFallbackIterator;
     use icu_locid_transform::fallback::LocaleFallbackPriority;
-    use icu_locid_transform::fallback::LocaleFallbacker;
     use icu_locid_transform::fallback::LocaleFallbackerWithConfig;
+    use icu_locid_transform::LocaleFallbacker;
 
     use crate::{
         errors::ffi::ICU4XError, locale::ffi::ICU4XLocale, provider::ffi::ICU4XDataProvider,

provider/adapters/src/fallback/mod.rs

@@ -126,7 +126,7 @@ impl<P> LocaleFallbackProvider<P> {
     ///
     /// ```
     /// use icu_locid::locale;
-    /// use icu_locid_transform::fallback::LocaleFallbacker;
+    /// use icu_locid_transform::LocaleFallbacker;
     /// use icu_provider::hello_world::*;
     /// use icu_provider::prelude::*;
     /// use icu_provider_adapters::fallback::LocaleFallbackProvider;

provider/core/src/fallback.rs

@@ -65,7 +65,7 @@ pub struct LocaleFallbackConfig {
     /// use icu_locid::locale;
     /// use icu_locid_transform::fallback::LocaleFallbackConfig;
     /// use icu_locid_transform::fallback::LocaleFallbackPriority;
-    /// use icu_locid_transform::fallback::LocaleFallbacker;
+    /// use icu_locid_transform::LocaleFallbacker;
     ///
     /// // Set up the fallback iterator.
     /// let fallbacker = LocaleFallbacker::new();
@@ -93,7 +93,7 @@ pub struct LocaleFallbackConfig {
     /// use icu_locid::locale;
     /// use icu_locid_transform::fallback::LocaleFallbackConfig;
     /// use icu_locid_transform::fallback::LocaleFallbackPriority;
-    /// use icu_locid_transform::fallback::LocaleFallbacker;
+    /// use icu_locid_transform::LocaleFallbacker;
     ///
     /// // Set up the fallback iterator.
     /// let fallbacker = LocaleFallbacker::new();
@@ -122,7 +122,7 @@ pub struct LocaleFallbackConfig {
     /// ```
     /// use icu_locid::locale;
     /// use icu_locid_transform::fallback::LocaleFallbackConfig;
-    /// use icu_locid_transform::fallback::LocaleFallbacker;
+    /// use icu_locid_transform::LocaleFallbacker;
     ///
     /// // Set up the fallback iterator.
     /// let fallbacker = LocaleFallbacker::new();
@@ -159,7 +159,7 @@ pub struct LocaleFallbackConfig {
     /// use icu_locid_transform::fallback::LocaleFallbackConfig;
     /// use icu_locid_transform::fallback::LocaleFallbackPriority;
     /// use icu_locid_transform::fallback::LocaleFallbackSupplement;
-    /// use icu_locid_transform::fallback::LocaleFallbacker;
+    /// use icu_locid_transform::LocaleFallbacker;
     ///
     /// // Set up the fallback iterator.
     /// let fallbacker = LocaleFallbacker::new();

provider/datagen/src/driver.rs

@@ -7,7 +7,7 @@ use crate::FallbackMode;
 use icu_locid::extensions::unicode::key;
 use icu_locid::LanguageIdentifier;
 use icu_locid_transform::fallback::LocaleFallbackIterator;
-use icu_locid_transform::fallback::LocaleFallbacker;
+use icu_locid_transform::LocaleFallbacker;
 use icu_provider::datagen::*;
 use icu_provider::prelude::*;
 use once_cell::sync::Lazy;