Documentation improvements / Trouble understanding simple use cases

[gerritsangel]

Hello,

I would like to raise a few problems with the current documentation, which I would like to improve a bit. Personally, I'm pretty confident with the “new” Java Time APIs and actually learned quite a bit of time handling based on them. With that in mind, I find chrono a bit hard to grasp with some of the simple use cases, which I think the Java API handles quite well:

1. Handling time zones (in contrast to only offsets) and conversions from datetimes without any time zone to one with (e.g. LocalDateTime to OffsetDateTime.
2. Basically converting from every class to another just by providing missing values (e.g. adding time to a LocalDate to get to a LocalDateTime, and then add a timezone to get a ZonedDateTime and then strip of the timezone and get only an offset to get to a OffsetDateTime).
3. Basically it's also possible in a Java IDE to just get the autocomplete and then just autocomplete throughout the classes until you get the correct result, without really making any errors.

I find this relatively difficult in chrono because of the concept of the TimeZone trait (Utc and Local as implementations of the struct, and then how does an explicit timezone fit into this?) and the whole usage of generic (which in my opinion tend to make Rust crates often quite difficult to understand, especially for newcomers). This is actually not bad from an API perspective, but I think it could have some more examples.

Furthermore, I think the whole topic of timezones is pushed to the sidelines by mentioning chrono-tz in the last sentence (and not mentioning tzfile). Imho, it would be much better if this topic would be mentioned right away next to when explaining Utc, Local and FixedOffset, as this topic is really quite important (E.g. often you only have a NaiveDateTime but still you know the timezone, instead of the offset and, want to transfer it to some DateTime with an offset).

I would also say that some kind of cookbook in a more prosa style would really benefit this crate, or maybe actually even a chrono book which explains some of the timezone concepts with code explanations.

[djc]

Hey, I recently took over as a maintainer after a prolonged period of very little attention being spent on the crate by the previous maintainer. As such, the documentation will not be my main focus for the near future. If you can make concrete proposals (ideally as a PR), I'd be very happy to review those, but otherwise this will have to wait a bit.

[gerritsangel]

Hi, sure no problem :) I just wanted to check whether I'm the only one with the problems.

Generally I would say to add a bit more verbose text in the module documentation would help a bit (even if it's clear to experienced Rust developers). In the future, I would definitely like to write a book about the whole topic, similar to other Rust crates with a more complex background.