icu4x
icu4x copied to clipboard
Minor cleanups to icu_locid docs
@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::Regionand elsewhere (includingVariantsand 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_sliceacross 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
Attributeand 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
lctoexpanderandcanonicalizer - [ ] In LocaleExpander, change one of the examples to use a LanguageIdentifier to demonstrate that the functions work with both Locale and with LanguageIdentifier