From 12823d9ca859f6d1817369c23d660558d78ad88f Mon Sep 17 00:00:00 2001
From: "Shane F. Carr" <shane@unicode.org>
Date: Wed, 6 Dec 2023 11:48:50 -0800
Subject: [PATCH] Document invariants in LocaleFallbacker

---
 .../src/fallback/algorithms.rs                |  2 +-
 .../locid_transform/src/fallback/mod.rs       | 70 +++++++++----------
 2 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/components/locid_transform/src/fallback/algorithms.rs b/components/locid_transform/src/fallback/algorithms.rs
index c3a3d08cab7..830aba3e7ed 100644
--- a/components/locid_transform/src/fallback/algorithms.rs
+++ b/components/locid_transform/src/fallback/algorithms.rs
@@ -298,7 +298,7 @@ mod tests {
             expected_region_chain: &["en-US-u-sd-usca", "en-US", "und-US-u-sd-usca", "und-US"],
         },
         TestCase {
-            // NOTE: -u-rg is not yet supported; when it is, this test should be updated
+            // TODO(#4413): -u-rg is not yet supported; when it is, this test should be updated
             input: "en-u-rg-gbxxxx",
             requires_data: false,
             extension_key: None,
diff --git a/components/locid_transform/src/fallback/mod.rs b/components/locid_transform/src/fallback/mod.rs
index 9dd835419c6..b2cb893c5c6 100644
--- a/components/locid_transform/src/fallback/mod.rs
+++ b/components/locid_transform/src/fallback/mod.rs
@@ -4,40 +4,6 @@
 
 //! Tools for locale fallback, enabling arbitrary input locales to be mapped into the nearest
 //! locale with data.
-//!
-//! The algorithm implemented in this module is called [Flexible Vertical Fallback](
-//! https://docs.google.com/document/d/1Mp7EUyl-sFh_HZYgyeVwj88vJGpCBIWxzlCwGgLCDwM/edit).
-//! Watch [#2243](https://github.com/unicode-org/icu4x/issues/2243) to track improvements to
-//! this algorithm and steps to enshrine the algorithm in CLDR.
-//!
-//! # Examples
-//!
-//! ```
-//! use icu_locid::locale;
-//! use icu_locid_transform::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());
-//! ```
 
 use crate::provider::*;
 use icu_locid::extensions::unicode::Value;
@@ -52,9 +18,17 @@ mod algorithms;
 /// Implements the algorithm defined in *[UTS #35: Locale Inheritance and Matching]*.
 ///
 /// Note that this implementation performs some additional steps compared to the *UTS #35*
-/// algorithm, see *[the design doc]* for a detailed description, and [#2243](
+/// 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*.
 ///
+/// If running fallback in a loop, use [`DataLocale::is_und()`] to break from the loop.
+///
+/// # Algorithm Invariants
+///
+/// 1. The [language identifier] will eventually reach `und`.
+/// 2. The Unicode extension keywords will eventually be removed.
+/// 3. The fallback chain requires context from the original input.
+///
 /// # Examples
 ///
 /// ```
@@ -84,8 +58,34 @@ mod algorithms;
 /// assert_eq!(fallback_iterator.get(), &locale!("und").into());
 /// ```
 ///
+/// Unicode extension keywords take part in fallback, but [auxiliary keys]
+/// are not modified:
+///
+/// ```
+/// use icu_locid::locale;
+/// use icu_locid_transform::LocaleFallbacker;
+///
+/// let fallbacker = LocaleFallbacker::new();
+/// let mut fallback_iterator = fallbacker
+///     .for_config(Default::default())
+///     .fallback_for("en-US-u-sd-usca-x-aux".parse().unwrap());
+///
+/// assert_eq!(fallback_iterator.get().to_string(), "en-US-u-sd-usca-x-aux");
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get().to_string(), "en-US-x-aux");
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get().to_string(), "en-u-sd-usca-x-aux");
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get().to_string(), "en-x-aux");
+/// fallback_iterator.step();
+/// assert_eq!(fallback_iterator.get().to_string(), "und-x-aux");
+/// assert!(fallback_iterator.get().is_und());
+/// ```
+///
 /// [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
+/// [auxiliary keys]: icu_provider::AuxiliaryKeys
+/// [language identifier]: icu_locid::LanguageIdentifier
 #[doc(hidden)]
 #[derive(Debug, Clone, PartialEq)]
 pub struct LocaleFallbacker {