icu4x icon indicating copy to clipboard operation
icu4x copied to clipboard

Minor cleanups to icu_locid docs

Open sffc opened this issue 3 years ago • 0 comments

@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

sffc avatar Sep 17 '22 01:09 sffc