Skip to content

Minor cleanups to icu_locid docs #2574

@sffc

Description

@sffc

@markusicu had the following suggestions for icu_locid docs that don't affect the API surface:

  • In various functions that take UTF-8 bytes, change it to say "ASCII bytes" since locale identifiers don't actually need full UTF-8.
  • Likewise, "BCP-47 string" should be "BCP-47 ASCII string" and "BCP-47 bytes" should be "BCP-47 ASCII bytes"
  • LanguageIdentifier::normalizing_eq() has a typo (should be “structural”)
  • Several functions have important documentation that is hidden below the examples section; they should be moved up above the examples:
    • from_locale_bytes
    • icu::locid::subtags::Language
    • Possibly others
  • In icu::locid::subtags::Language, consolidate the two "Examples" section into a single section
  • In icu::locid::subtags::Language, change the "Notice" to "Note"
  • In icu::locid::subtags::Language (and possibly elsewhere), add an example of what happens when you give an input string with incorrectly cased ASCII
  • In the from_raw_unchecked, change the phrasing from "only takes" to "should only be called with"
  • In icu::locid::subtags::Region and elsewhere (including Variants and probably more places), the .expect("Parsing failed") wording is misleading; it makes it looks as if the string is expected to fail to parse. I suggest changing it to a more neutral string such as .expect("parsing").
  • In icu::locid::Variants, add an example with a 4-digit variant such as "1994" in "sl-IT-rozaj-biske-1994"
  • In icu::locid::Locale, add an assertion in the main example that the "-u-hc-h12" extension got parsed correctly
  • In from_bytes_manual_slice across the board, rename the "end" argument to "limit" to clarify that it is an exclusive limit (we already do this in a few places, and ICU4C uses this convention as well)
  • In Attribute and elsewhere, reword "alphanumerical bytes" to say that they are ASCII bytes
  • In unicode::Unicode, reorder the struct fields to put attributes before keywords

And also in icu_locid_transform:

  • Change the variable name in the docs examples from lc to expander and canonicalizer
  • In LocaleExpander, change one of the examples to use a LanguageIdentifier to demonstrate that the functions work with both Locale and with LanguageIdentifier

Metadata

Metadata

Assignees

Labels

C-localeComponent: Locale identifiers, BCP47S-smallSize: One afternoon (small bug fix or enhancement)T-docs-testsType: Code change outside core library

Type

No type

Projects

No projects

Relationships

None yet

Development

No branches or pull requests

Issue actions