Markus Feedback on DateTime API

[sffc]

There are a number of issues, mostly docs, that need to be addressed based on feedback from @markusicu.

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

Modulo these changes, the new icu_datetime crate has the i18n approval.

[Manishearth]

Checklist:

• hm() -> with_hm()
• In the docs for fieldsets::enums we can replace the [true, false].map with just two function calls.
• In the fieldsets docs: "There are two ways to configure…"
• In the Combo docs: "The only way to construct…"
• In the Combo docs: Combo<ET, Location> is kind of confusing. Maybe have an explicit import there? Combo<fieldsets::ET, fieldsets::zone::Location>. Manish also likes Combo<ET, zone::Location>, ET is a bit of an outlier when it comes to fsets
• Shane: last example in Combo could be using NoCalendarFormatter
• We shouldn’t have discriminants on Length, they’re not used anymore. Shouldn’t be repr(u8) either.
• SubsecondError: error range is 1-9, not 0-9
• TimePrecision: example should use NoCalendarFormatter instead of FixedCalendarDateTimeFormatter::<(), _>. Also remove the format string from assert_writeable_eq.
• Remove apostrophe from ’24 from YearStyle::Auto
• DateTimeFormatter::try_new refers to a "with_components" which no longer exists
• Rename field_set parameters to field_set_and_options or field_set_with_options. Keep FSet parameters named the same. Split to Language involving "field set", "field set with options", and "semantic skeleton" #6472
• "enabled with the serde feature" should say "Cargo feature"
• Explicitly talk about the mechanism of data shaving from cast_into_fset() . Example should illustrate that you can use this when saving formatters of multiple different build-time field sets into the same variable. Do this on all types that have cast_into_fset()
• FixedCalendarDateTimeFormatter: add comment that "Gregorian" is implied by the compiler by passing in a Gregorian date to the format function, Or add an example where the type is implied. Consider moving "Mismatched calendars will not compile" example into main FixedCalendarDateTimeFormatter docs?
• NoCalendarFormatter: start with an example that works rather than one that gives an error
• Might be nice to reduce verbosity of with_time_precision(SubsecondDigits::...). Maybe add with_time_precision_subsecond? (check docs for RObert's comments too)
• icu::datetime::preferences types don't seem to indicate that they are re-exported??
• DateTimePattern: when Markus reads "pattern" it implies it is a string, but that isn't the case here because the type is named Pattern. Maybe it's fine.
• DateTimePatternFormatter: the example should show where exactly the formatter is being created (rather than hiding it inside assert_writeable_eq). Maybe have a try_new that takes the two arguments as input, instead of factory methods? Might be more obvious. Or at least save the formatter into a variable.
• FixedCalendarDateTimeNames: the docs should say "field sets" instead of "components". "and error will occur" ⇒ "an error will occur"
• FixedCalendarDateTimeNames: the include functions should say with compiled data and have a compiled_data feature alert
• FixedCalendarDateTimeNames::with_pattern_unchecked: should say when you use this function: if you know at compile time what fields your pattern contains
• Link to Handle multiple lengths of the same field in DateTimeNames #4337 is not a link; it should go somewhere (to GItHub)
• MonthNameLength: Add docs that this is not just the length; it is also the type. You can explain it; probably doesn't need to be in the name because that would be very long.

[Manishearth]

I've checked items handled in #6423 above

[sffc]

Might be nice to reduce verbosity of with_time_precision(SubsecondDigits::...). Maybe add with_time_precision_subsecond? (check docs for Robert's comments too)

I added hmss functions that directly take a SubsecondDigits argument:

// before
YMD::medium().with_time(TimePrecision::Subsecond(S2))

// after
YMD::medium().with_time_hmss(S2)

// note: we also have hm and hms
YMD::medium().with_time_hm()
YMD::medium().with_time_hms()