Add on overview to DateTime

src/datetime/mod.rs

@@ -79,11 +79,121 @@ pub enum SecondsFormat {
     __NonExhaustive,
 }
 
-/// ISO 8601 combined date and time with time zone.
+/// `DateTime` is the preferred type for working with real-world timestamps. It contains all the
+/// information needed to exactly specify a point in time, and to do calculations on it: a date,
+/// time, offset from UTC, and timezone.
 ///
-/// There are some constructors implemented here (the `from_*` methods), but
-/// the general-purpose constructors are all via the methods on the
-/// [`TimeZone`](./offset/trait.TimeZone.html) implementations.
+/// Internally it stores the information as a UTC [`NaiveDateTime`] and a generic type implementing
+/// [`Offset`]. The offset can be a zero-sized type such as for [`Utc`], or contain some value to
+/// store the offset from UTC. The type implementing the [`TimeZone`] is tracked by the type system.
+///
+/// # Timezones
+///
+/// [`DateTime`] is generic over types implementing [`TimeZone`]. There are the following choices:
+/// - [`Utc`] is the universal time other timezones are defined against. It is continuous, without
+///   gaps or ambiguities like common timezones.
+/// - [`FixedOffset`] is useful when only the offset from UTC must be stored, without knowing to
+///   which real timezone it belongs. This is generally not what you want when you need to do time
+///   or date calculations with this [`DateTime`].
+/// - [`Local`] matches the current timezone settings of the operating system. Unix and Windows have
+///   simplified timezone implementations however that can't fully describe all complexities like
+///   the IANA timezone database does.
+/// - Types implementing proper timezone support such as in [`chrono_tz`](
+///   https://docs.rs/chrono-tz/latest/chrono_tz/index.html).
+///
+/// # Creating a `DateTime`
+///
+/// ## Combine from primitive types
+/// Methods are available on multiple types for convenience.
+/// - Combine a [`TimeZone`] and a _local_ [`NaiveDateTime`]:
+///   - [`NaiveDateTime::and_local_timezone`]
+///   - [`TimeZone::from_local_datetime`]
+///   - [`DateTime<Tz: TimeZone>::from_local`]
+/// - Combine a [`TimeZone`] and a _UTC_ [`NaiveDateTime`]:
+///   - [`TimeZone::from_utc_datetime`]
+///   - [`DateTime<Tz: TimeZone>::from_utc`]
+/// - (convenience) Combine a [`TimeZone`] with _local_ year, month, day and time components:
+///   - [`TimeZone::with_ymd_and_hms`]
+///
+/// ## From the current time
+/// (Requires the default `clock` feature.)
+/// - [`Local.now()`](offset/struct.Local.html#method.now)
+/// - [`Utc.now()`](offset/struct.Utc.html#method.now)
+///
+/// ## Parsing
+/// - [`parse_from_str`](#method.parse_from_str) for parsing with a format string
+/// - [`parse_from_rfc2822`](#method.parse_from_rfc2822) for parsing a string such as
+///   `Tue, 1 Jul 2003 10:52:37 +0200` to a [`DateTime<FixedOffset>`]
+/// - [`parse_from_rfc3339`](#method.parse_from_rfc3339) for parsing a string such as
+///   `2003-07-01T10:52:37+02:00` to a [`DateTime<FixedOffset>`]
+/// - [`TimeZone::datetime_from_str`] parsing from a string without timezone information
+///   (or with an offset that must match that of the timezone)
+///
+/// ## From common external types:
+/// - Combine a [`TimeZone`] with a UTC Unix timestamp:
+///   - [`TimeZone::timestamp_opt`]
+///   - [`TimeZone::timestamp_millis_opt`]
+///   - [`TimeZone::timestamp_nanos`]
+/// - From the standard library [`SystemTime`](
+///   https://doc.rust-lang.org/std/time/struct.SystemTime.html) (requires the default `std`
+///   feature):
+///   - [`DateTime<Utc>::from`](#impl-From<SystemTime>-for-DateTime<Utc>)
+///   - [`DateTime<Local>::from`](#impl-From<SystemTime>-for-DateTime<Local>)
+///
+/// # Working with `DateTime`s
+///
+/// ## Getting components
+/// For more complex operations on a [`DateTime`], it is best to decompose it into its individual
+/// components and work with those:
+///
+/// - [`naive_utc`](#method.naive_utc) returns a view to the UTC [`NaiveDateTime`].
+/// - [`local_utc`](#method.local_utc) gets the a [`NaiveDateTime`] as local time.
+/// - [`date`](#method.date) is a convenience method to get a local [`NaiveDate`].
+/// - [`time`](#method.time) is a convenience method to get a local [`NaiveTime`].
+/// - [`offset`](#method.offset) retrieves the associated offset from UTC.
+/// - [`timezone`](#method.timezone) reconstructs the timezone.
+///
+/// ## Modifying date and time
+/// Methods to examine the date and do basic modifications are implemented as part the [`Datelike`]
+/// trait. Similarly the [`Timelike`] trait is implemented to examine and do basic modifications to
+/// the time.
+///
+/// Timezone-aware calculations on a [`DateTime`] can be done with:
+/// - [`Sub<DateTime>`] to get a [`Duration`](struct.Duration.html) with the difference between two
+///   datetimes.
+/// - [`Add<Duration>`] to add a [`Duration`](struct.Duration.html) of an absolute number of
+///   seconds, minutes, hours, etc.
+/// - [`Add<Days>`] to add a number of [`Days`], keeping the same local time. This method may panic
+///   if the resulting time would not exist, prefer [`checked_add_days`](#method.checked_add_days).
+/// - [`Add<Months>`] to add a number of [`Months`], keeping the same local time. See the preferred
+///   [`checked_add_months`](#method.checked_add_months) method for implementation details.
+///
+/// TODO: [`DurationRound`]
+///
+/// ## Change the timezone
+/// Various [`From`](https://doc.rust-lang.org/std/convert/trait.From.html) implementations are
+/// available to convert between [`DateTime<Utc>`], [`DateTime<FixedOffset>`] and
+/// [`DateTime<Local>`].
+///
+/// - [`with_timezone`](#method.with_timezone) changes the associated timezone, without altering the
+///    UTC instant in time.
+/// - [`fix_offset`](#method.fix_offset) can convert a generic [`DateTime`] to
+///   [`DateTime<FixedOffset>`].
+///
+/// # Convert to external types
+///
+/// - [`timestamp`](#method.timestamp) returns an UTC Unix timestamp.
+/// - [`timestamp_millis`](#method.timestamp_millis)
+/// - [`timestamp_micros`](#method.timestamp_micros)
+/// - [`timestamp_nanos`](#method.timestamp_nanos)
+///
+/// TODO
+/// - [`timestamp_subsec_millis`](#method.timestamp_subsec_millis)
+/// - [`timestamp_subsec_micros`](#method.timestamp_subsec_micros)
+/// - [`timestamp_subsec_nanos`](#method.timestamp_subsec_nanos)
+///
+/// - [`impl<Tz: TimeZone> From<DateTime<Tz>> for SystemTime`]
+
 #[derive(Clone)]
 #[cfg_attr(feature = "rkyv", derive(Archive, Deserialize, Serialize))]
 pub struct DateTime<Tz: TimeZone> {