Feedback on `icu_time` API

[robertbastian]

https://docs.google.com/document/d/1gKZCaiTG2eeyxrIKUF2tf6PIsaPCIBaUVRXD-JDh6dI/edit?tab=t.0#heading=h.zfxbicahzeqi

[sffc]

API Breaking:

• [x] Return the TimeZone BCP 47 as a Subtag
• [ ] Revisit naming convention of is_default on Locale types (split to #6505)
  • Note: The und language subtag is short for "undetermined" in the registry
  • Note: Maybe have is_unknown() on all of these: Locale, TimeZone, etc. It is a useful predicate to have. This is one of the more successful things we've had in III.
• [x] IanaParserExtendedBorrowed::parse should return a struct with named fields. Markus: That would definitely be nicer.
• [x] Revisit naming of subsecond field to make sure it is clear that it is in nanoseconds. At least explain clearly in docs.
  • Markus says: Subsecond doesn't say where it is millisecond or nanosecond. Call sites that call .subsecond() are unclear. (again later in ZonedDateTime::try_from_str)
• [x] Don't have the midnight() constructor. Call it zero() or something. I expect midnight() to be the end of the day. Rob: or start_of_day().
• [x] ZonedDateTime: Markus says: How about "lenient" instead of "loose". Or "generic" or something. "loose" is not a good opposite of "strict".
• [x] ZonedDateTime: try_from_str should be more explicit what it needs. Rob: try_full_from_str?

High Impact Non-Breaking:

• [ ] Better docs to explain how to make an offset-only time zone (use unknown and add an offset)
• [ ] Better docs to explain what TimeZoneInfo is and what it does and why it's different from a TimeZone
  • Markus said: I see why you decouple time zone ID from offset, to reduce data dependencies, but you should explain that more. It is counterintuitive compared to how most i18n libraries work.
• [ ] You should talk about where people should get the offset and variant. Links to the chrono and jiff examples should be fine.
• [ ] TimeZoneInfo: Improve docs regarding the multiple different reckonings
  • Markus says: Why are the functions in different sections? Are the ones on top (time_zone_id, offset) the main functions?
  • Shane says: Not convinced that TimeZoneInfo with generics was the right API. Would have rather had three TimeZoneInfo types instead. Markus says: Feels weird that these are the same type. They should be subclasses, but you can't do subclasses. If Rust people think this is OK, then fine. Robert says: The docs at least need to be improved.
• [ ] DateTime: Show example of manual construction with public fields, not just a string
• [ ] ZonedDateTime: Need Examples on the parse functions!
• [ ] ZonedDateTIme: Not super clear that these parse functions return different types.
• [ ] TimeZoneVariant: Needs more sample code. infer_zone_variant, too.
• [ ] UtcOffset: from_eighths_of_hour is weird and it shouldn't be public API. Should be internal. Shane says: We could weasel around this by exporting a type from the scaffold module instead.
• [x] IanaParser: Maybe add is_unknown()? More ergonomic than == TimeZone::unknown()

Moderate Impact Non-Breaking:

• [ ] IanaParser vs IanaParserBorrowed is confusing and makes methods less discoverable
  • Markus says: It looks like the operations are slower and faster, and both have the same functions. But they don't.
  • Markus says: A parser that doesn't parse is a misnomer
  • Manish says: This is an ICU4X pattern. we should have central docs for it.
• [ ] Better docs on TimeZoneModel
• [ ] Prefer using IANA over BCP-47 like "uschi" in examples
• [x] Link from TimeZone and TimeZoneInfo to the zone module which has more examples
• [x] zone module: "[formattable time zone]" is broken link
• [x] zone module: The docs say "metazone" but you shouldn't introduce that terminology here
• [x] zone module: "Europe/Lismob/ptlis" looks like one ID. Write the word "or"
• [x] IanaParser: "8 ASCII characters or less" should be "fewer". Also "less than 40" should be "fewer"
• [x] IanaParser: Is the average "5.1 characters" useful info?
• [x] IanaParser: Need to move the Normalize/Canonicalize docs to the correct type
• [x] Need more docs on IanaParserExtended[Borrowed]
• [ ] Document why we need to return 3 values here (The strings are interned.)
• [x] Do not assert the number of time zones (445, 598). Change it to be >.
• [x] Windows parser: please fix docs [Region] link
• [x] DateTime: link to Date broken?
• [x] Use the RFC number over IXDTF in general
• [x] DateTime: try_from_str should maybe say IXDTF. Rob: Our Locale docs don't say that. Markus: For locales, it's obvious that's what you want, but it's not clear that argument applies here.
• [ ] DateTime: Add example about mismatched calendar in string and function in try_from_str
• [ ] Hour, Minute, Second, Nanosecond: where's the constructor? There is the TryFrom impl. Not discoverable.
  • Shane says: I'd support adding try_from_usize, similar to how we have try_from_str. Rob: People don't usually need to construct these.
• [x] "There is no name for America/Los_Angeles never at" is not a sentence
• [x] UtcOffset: Please document the range

[sffc]

Revisit naming of subsecond field to make sure it is clear that it is in nanoseconds. At least explain clearly in docs.

The field is pub subsecond: Nanosecond which I find fairly clear.

[sffc]

@robertbastian I made a checklist and followed up on the breaking items. I'd like if we can also resolve the items I categorized as "High Impact Non-Breaking" before the 2.0 release. Some of them might already be fixed, but I didn't check.

[sffc]

Split the ZonedDateTime docs changes into https://github.com/unicode-org/icu4x/issues/6524