Add docs tests for SubdivisionId and preferences types (#7347)

Split from #7335

Author: sffc

components/locale_core/src/extensions/unicode/subdivision.rs

@@ -74,6 +74,7 @@ impl SubdivisionSuffix {
 ///     subtags::region,
 /// };
 ///
+/// // "zzzz" means "unknown subdivision"
 /// let ss = subdivision_suffix!("zzzz");
 /// let region = region!("gb");
 ///
@@ -114,6 +115,48 @@ impl SubdivisionId {
 
     /// A constructor which takes a str slice, parses it and
     /// produces a well-formed [`SubdivisionId`].
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use icu::locale::extensions::unicode::SubdivisionId;
+    /// use writeable::assert_writeable_eq;
+    ///
+    /// let subdivision = SubdivisionId::try_from_str("gbeng").unwrap();
+    ///
+    /// assert_writeable_eq!(subdivision, "gbeng");
+    /// assert_writeable_eq!(subdivision.region, "GB");
+    /// assert_writeable_eq!(subdivision.suffix, "eng");
+    /// ```
+    ///
+    /// When the value can't be parsed:
+    ///
+    /// ```
+    /// use icu::locale::extensions::unicode::SubdivisionId;
+    /// use icu::locale::ParseError;
+    ///
+    /// // Value is too short
+    /// assert!(matches!(
+    ///     SubdivisionId::try_from_str("zz"),
+    ///     Err(ParseError::InvalidExtension),
+    /// ));
+    ///
+    /// // Value is too long
+    /// assert!(matches!(
+    ///     SubdivisionId::try_from_str("abcdefg"),
+    ///     Err(ParseError::InvalidExtension),
+    /// ));
+    ///
+    /// // Value does not start with a valid region code
+    /// assert!(matches!(
+    ///     SubdivisionId::try_from_str("a0zzzz"),
+    ///     Err(ParseError::InvalidExtension),
+    /// ));
+    /// assert!(matches!(
+    ///     SubdivisionId::try_from_str("0azzzz"),
+    ///     Err(ParseError::InvalidExtension),
+    /// ));
+    /// ```
     #[inline]
     pub fn try_from_str(s: &str) -> Result<Self, ParseError> {
         Self::try_from_utf8(s.as_bytes())

components/locale_core/src/preferences/extensions/unicode/keywords/region_override.rs

@@ -10,6 +10,26 @@ struct_keyword!(
     /// A Region Override specifies an alternate region to use for obtaining certain region-specific default values.
     ///
     /// The valid values are listed in [LDML](https://unicode.org/reports/tr35/#RegionOverride).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use icu::locale::locale;
+    /// use icu::locale::extensions::unicode::key;
+    /// use icu::locale::preferences::extensions::unicode::keywords::RegionOverride;
+    /// use writeable::assert_writeable_eq;
+    ///
+    /// // American English with British user preferences
+    /// let locale = locale!("en-US-u-rg-gbzzzz");
+    ///
+    /// let normal_region = locale.id.region.unwrap();
+    /// let rg_extension_value = locale.extensions.unicode.keywords.get(&key!("rg")).unwrap();
+    /// let region_override = RegionOverride::try_from(rg_extension_value.clone()).unwrap();
+    ///
+    /// assert_writeable_eq!(normal_region, "US");
+    /// assert_writeable_eq!(region_override.region, "GB");
+    /// assert_writeable_eq!(region_override.suffix, "zzzz");
+    /// ```
     [Copy]
     RegionOverride,
     "rg",

components/locale_core/src/preferences/extensions/unicode/keywords/regional_subdivision.rs

@@ -13,6 +13,40 @@ struct_keyword!(
     /// A Unicode Subdivision Identifier defines a regional subdivision used for locales.
     ///
     /// The valid values are listed in [LDML](https://unicode.org/reports/tr35/#UnicodeSubdivisionIdentifier).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use icu::locale::locale;
+    /// use icu::locale::extensions::unicode::key;
+    /// use icu::locale::preferences::extensions::unicode::keywords::RegionalSubdivision;
+    /// use writeable::assert_writeable_eq;
+    ///
+    /// // Texan English
+    /// let locale = locale!("en-US-u-sd-ustx");
+    ///
+    /// let normal_region = locale.id.region.unwrap();
+    /// let sd_extension_value = locale.extensions.unicode.keywords.get(&key!("sd")).unwrap();
+    /// let regional_subdivision = RegionalSubdivision::try_from(sd_extension_value.clone()).unwrap();
+    ///
+    /// assert_writeable_eq!(normal_region, "US");
+    /// assert_writeable_eq!(regional_subdivision.region, "US");
+    /// assert_writeable_eq!(regional_subdivision.suffix, "tx");
+    /// ```
+    ///
+    /// The subdivision "true" is not supported; see [CLDR-19163](https://unicode-org.atlassian.net/browse/CLDR-19163):
+    ///
+    /// ```
+    /// use icu::locale::extensions::unicode::value;
+    /// use icu::locale::preferences::extensions::unicode::keywords::RegionalSubdivision;
+    /// use icu::locale::preferences::extensions::unicode::errors::PreferencesParseError;
+    /// use writeable::assert_writeable_eq;
+    ///
+    /// assert!(matches!(
+    ///     RegionalSubdivision::try_from(value!("true")),
+    ///     Err(PreferencesParseError::InvalidKeywordValue),
+    /// ));
+    /// ```
     [Copy]
     RegionalSubdivision,
     "sd",