Add more documentation to TimeZone
#1068
Conversation
src/offset/mod.rs
Outdated
| /// A type implementing [`TimeZone`] can be used to create a [`DateTime`]: | ||
| /// | ||
| /// Creating a [`DateTime`] from a [`NaiveDateTime`]: | ||
| /// - [`from_local_datetime`](#method.from_local_datetime) if the datetime is local. |
There was a problem hiding this comment.
... is in local timezone.
| @@ -209,10 +209,118 @@ pub trait Offset: Sized + Clone + fmt::Debug { | |||
| fn fix(&self) -> FixedOffset; | |||
| } | |||
|
|
|||
| /// The time zone. | |||
| /// The [`TimeZone`] trait is the backbone of chrono, allowing it to work with local time. | |||
There was a problem hiding this comment.
The first line should explain what it is, and doesn't need to repeat the name itself. "backbone of chrono" doesn't convey anything particularly useful to a reader trying to familiarize themselves with what it does, and "allowing it to work with local time" seems kinda vague.
Maybe something like "Represents a time zone to help distinguish between timestamps from different zones"?
| /// Most methods of this trait are deprecated, it is usually better or easier to work with the | ||
| /// methods on [`DateTime`] and [`NaiveDateTime`] instead. |
There was a problem hiding this comment.
Leading off with "Most methods of this trait are deprecated" seems like a bad way to explain the trait. Before "Using TimeZone" we should probably start with a more detailed description of what TimeZone is and what it contains.
| /// [`from_offset`](#tymethod.from_offset) allows the type to be reconstructed from the associated | ||
| /// [`Offset`] type, which gets stored in a [`DateTime`]. | ||
| /// | ||
| /// ## Example |
There was a problem hiding this comment.
I think I'd prefer not to have an example for implementing TimeZone. Creating new TimeZone implementations should be pretty rare, and finding the implementations in the chrono code base and inspecting their source code is pretty straightforward, so it seems low value to have a bunch of code here.
| /// A type implementing [`TimeZone`] can be used to create a [`DateTime`]: | ||
| /// | ||
| /// Creating a [`DateTime`] from a [`NaiveDateTime`]: | ||
| /// - [`from_local_datetime`](#method.from_local_datetime) if the datetime is in local time zone. | ||
| /// - [`from_utc_datetime`](#method.from_utc_datetime) if the datetime is in UTC time zone. | ||
| /// | ||
| /// Creating a [`DateTime`] from a Unix timestamp in UTC: | ||
| /// - [`timestamp_opt`](#method.timestamp_opt) | ||
| /// - [`timestamp_millis_opt`](#method.timestamp_millis_opt) | ||
| /// - [`timestamp_nanos`](#method.timestamp_nanos) | ||
| /// | ||
| /// Creating a [`DateTime`] from year, month, day, time components: | ||
| /// - [`with_ymd_and_hms`](#method.with_ymd_and_hms) | ||
| /// | ||
| /// Parsing a [`DateTime`] from a string: | ||
| /// - [`datetime_from_str`](#method.datetime_from_str). Note that if the string contains an offset | ||
| /// from UTC, that offset must match the timezone at that point in time. |
There was a problem hiding this comment.
This seems to mainly advertise the TimeZone methods. IMO we should be advertising the NaiveDateTime methods that convert into DateTime here as alternatives.
|
I'll give this another try in the future. |
Split out from #1040.