Add documentation for time

* Add a simple module documentation, similar to the chrono one.
* Describe the new feature flag.
* Update the documentations for the Timestamp* and Duration* types, both
  where they are defined and in the transformations list.
* Add new transformations for the well-known Rfc2822 and Rfc3339 types.

serde_with/src/guide/feature_flags.md

@@ -10,6 +10,7 @@ Each entry will explain the feature in more detail.
 5. [`indexmap`](#indexmap)
 6. [`json`](#json)
 7. [`macros`](#macros)
+8. [`time_0_3`](#time_0_3)
 
 ## `base64`
 
@@ -52,3 +53,10 @@ The `macros` features enables all helper macros and derives.
 It is enabled by default, since the macros provide a usability benefit, especially for `serde_as`.
 
 This pulls in `serde_with_macros` as a dependency.
+
+## `time_0_3`
+
+The `time_0_3` enables integration of `time` v0.3 specific conversions.
+This includes support for the timestamp and duration types.
+
+This pulls in `time` v0.3 as a dependency.

serde_with/src/guide/serde_as_transformations.md

@@ -23,6 +23,7 @@ This page lists the transformations implemented in this crate and supported by `
 19. [Timestamps as seconds since UNIX epoch](#timestamps-as-seconds-since-unix-epoch)
 20. [Value into JSON String](#value-into-json-string)
 21. [`Vec` of tuples to `Maps`](#vec-of-tuples-to-maps)
+22. [Well-known time formats for `OffsetDateTime`](#well-known-time-formats-for-offsetdatetime)
 
 ## Base64 encode bytes
 
@@ -212,6 +213,8 @@ value: Duration,
 
 The same conversions are also implemented for [`chrono::Duration`] with the `chrono` feature.
 
+The same conversions are also implemented for [`time::Duration`] with the `time_0_3` feature.
+
 ## Hex encode bytes
 
 [`Hex`]
@@ -405,6 +408,8 @@ value: SystemTime,
 
 The same conversions are also implemented for [`chrono::DateTime<Utc>`], [`chrono::DateTime<Local>`], and [`chrono::NaiveDateTime`] with the `chrono` feature.
 
+The conversions are availble for [`time::OffsetDateTime`] and [`time::PrimitiveDateTime`] with the `time_0_3` feature enabled.
+
 ## Value into JSON String
 
 Some JSON APIs are weird and return a JSON encoded string in a JSON response
@@ -446,6 +451,25 @@ This includes `BinaryHeap<(K, V)>`, `BTreeSet<(K, V)>`, `HashSet<(K, V)>`, `Link
 
 The [inverse operation](#maps-to-vec-of-tuples) is also available.
 
+## Well-known time formats for `OffsetDateTime`
+
+[`time::OffsetDateTime`] can be serialized in string format in different well-known formats.
+Two formats are supported, [`time::format_description::well_known::Rfc2822`] and [`time::format_description::well_known::Rfc3339`].
+
+```ignore
+// Rust
+#[serde_as(as = "time::format_description::well_known::Rfc2822")]
+rfc_2822: OffsetDateTime,
+#[serde_as(as = "time::format_description::well_known::Rfc3339")]
+rfc_3339: OffsetDateTime,
+
+// JSON
+"rfc_2822": "Fri, 21 Nov 1997 09:55:06 -0600",
+"rfc_3339": "1997-11-21T09:55:06-06:00",
+```
+
+These conversions are availble with the `time_0_3` feature flag.
+
 [`Base64`]: crate::base64::Base64
 [`Bytes`]: crate::Bytes
 [`chrono::DateTime<Local>`]: chrono_crate::DateTime
@@ -464,6 +488,11 @@ The [inverse operation](#maps-to-vec-of-tuples) is also available.
 [`NoneAsEmptyString`]: crate::NoneAsEmptyString
 [`OneOrMany`]: crate::OneOrMany
 [`PickFirst`]: crate::PickFirst
+[`time::Duration`]: time_0_3::Duration
+[`time::format_description::well_known::Rfc2822`]: time_0_3::format_description::well_known::Rfc2822
+[`time::format_description::well_known::Rfc3339`]: time_0_3::format_description::well_known::Rfc3339
+[`time::OffsetDateTime`]: time_0_3::OffsetDateTime
+[`time::PrimitiveDateTime`]: time_0_3::PrimitiveDateTime
 [`TimestampSeconds`]: crate::TimestampSeconds
 [`TimestampSecondsWithFrac`]: crate::TimestampSecondsWithFrac
 [`TryFromInto`]: crate::TryFromInto

serde_with/src/lib.rs

@@ -264,9 +264,6 @@ pub mod base64;
 #[cfg(feature = "chrono")]
 #[cfg_attr(docsrs, doc(cfg(feature = "chrono")))]
 pub mod chrono;
-#[cfg(feature = "time_0_3")]
-#[cfg_attr(docsrs, doc(cfg(feature = "time_0_3")))]
-pub mod time_0_3;
 mod content;
 pub mod de;
 mod duplicate_key_impls;
@@ -282,6 +279,9 @@ pub mod json;
 pub mod rust;
 pub mod ser;
 mod serde_conv;
+#[cfg(feature = "time_0_3")]
+#[cfg_attr(docsrs, doc(cfg(feature = "time_0_3")))]
+pub mod time_0_3;
 mod utils;
 #[doc(hidden)]
 pub mod with_prefix;
@@ -749,13 +749,16 @@ pub struct BytesOrString;
 /// For example, deserializing `DurationSeconds<f64, Flexible>` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number.
 ///
 /// This type also supports [`chrono::Duration`] with the `chrono`-[feature flag].
+/// This type also supports [`time::Duration`][::time_0_3::Duration] with the `time_0_3`-[feature flag].
 ///
 /// | Duration Type         | Converter                 | Available `FORMAT`s    |
 /// | --------------------- | ------------------------- | ---------------------- |
 /// | `std::time::Duration` | `DurationSeconds`         | `u64`, `f64`, `String` |
 /// | `std::time::Duration` | `DurationSecondsWithFrac` | `f64`, `String`        |
 /// | `chrono::Duration`    | `DurationSeconds`         | `i64`, `f64`, `String` |
 /// | `chrono::Duration`    | `DurationSecondsWithFrac` | `f64`, `String`        |
+/// | `time::Duration`      | `DurationSeconds`         | `i64`, `f64`, `String` |
+/// | `time::Duration`      | `DurationSecondsWithFrac` | `f64`, `String`        |
 ///
 /// # Examples
 ///
@@ -889,13 +892,16 @@ pub struct DurationSeconds<
 /// For example, deserializing `DurationSeconds<f64, Flexible>` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number.
 ///
 /// This type also supports [`chrono::Duration`] with the `chrono`-[feature flag].
+/// This type also supports [`time::Duration`][::time_0_3::Duration] with the `time_0_3`-[feature flag].
 ///
 /// | Duration Type         | Converter                 | Available `FORMAT`s    |
 /// | --------------------- | ------------------------- | ---------------------- |
 /// | `std::time::Duration` | `DurationSeconds`         | `u64`, `f64`, `String` |
 /// | `std::time::Duration` | `DurationSecondsWithFrac` | `f64`, `String`        |
 /// | `chrono::Duration`    | `DurationSeconds`         | `i64`, `f64`, `String` |
 /// | `chrono::Duration`    | `DurationSecondsWithFrac` | `f64`, `String`        |
+/// | `time::Duration`      | `DurationSeconds`         | `i64`, `f64`, `String` |
+/// | `time::Duration`      | `DurationSecondsWithFrac` | `f64`, `String`        |
 ///
 /// # Examples
 ///
@@ -1069,6 +1075,7 @@ pub struct DurationNanoSecondsWithFrac<
 /// For example, deserializing `TimestampSeconds<f64, Flexible>` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number.
 ///
 /// This type also supports [`chrono::DateTime`][DateTime] with the `chrono`-[feature flag].
+/// This type also supports [`time::OffsetDateTime`][::time_0_3::OffsetDateTime] and [`time::PrimitiveDateTime`][::time_0_3::PrimitiveDateTime] with the `time_0_3`-[feature flag].
 ///
 /// | Timestamp Type            | Converter                  | Available `FORMAT`s    |
 /// | ------------------------- | -------------------------- | ---------------------- |
@@ -1078,6 +1085,10 @@ pub struct DurationNanoSecondsWithFrac<
 /// | `chrono::DateTime<Utc>`   | `TimestampSecondsWithFrac` | `f64`, `String`        |
 /// | `chrono::DateTime<Local>` | `TimestampSeconds`         | `i64`, `f64`, `String` |
 /// | `chrono::DateTime<Local>` | `TimestampSecondsWithFrac` | `f64`, `String`        |
+/// | `time::OffsetDateTime`    | `TimestampSeconds`         | `i64`, `f64`, `String` |
+/// | `time::OffsetDateTime`    | `TimestampSecondsWithFrac` | `f64`, `String`        |
+/// | `time::PrimitiveDateTime` | `TimestampSeconds`         | `i64`, `f64`, `String` |
+/// | `time::PrimitiveDateTime` | `TimestampSecondsWithFrac` | `f64`, `String`        |
 ///
 /// # Examples
 ///
@@ -1212,6 +1223,7 @@ pub struct TimestampSeconds<
 /// For example, deserializing `TimestampSeconds<f64, Flexible>` will discard any subsecond precision during deserialization from `f64` and will parse a `String` as an integer number.
 ///
 /// This type also supports [`chrono::DateTime`][DateTime] and [`chrono::NaiveDateTime`][NaiveDateTime] with the `chrono`-[feature flag].
+/// This type also supports [`time::OffsetDateTime`][::time_0_3::OffsetDateTime] and [`time::PrimitiveDateTime`][::time_0_3::PrimitiveDateTime] with the `time_0_3`-[feature flag].
 ///
 /// | Timestamp Type            | Converter                  | Available `FORMAT`s    |
 /// | ------------------------- | -------------------------- | ---------------------- |
@@ -1223,6 +1235,10 @@ pub struct TimestampSeconds<
 /// | `chrono::DateTime<Local>` | `TimestampSecondsWithFrac` | `f64`, `String`        |
 /// | `chrono::NaiveDateTime`   | `TimestampSeconds`         | `i64`, `f64`, `String` |
 /// | `chrono::NaiveDateTime`   | `TimestampSecondsWithFrac` | `f64`, `String`        |
+/// | `time::OffsetDateTime`    | `TimestampSeconds`         | `i64`, `f64`, `String` |
+/// | `time::OffsetDateTime`    | `TimestampSecondsWithFrac` | `f64`, `String`        |
+/// | `time::PrimitiveDateTime` | `TimestampSeconds`         | `i64`, `f64`, `String` |
+/// | `time::PrimitiveDateTime` | `TimestampSecondsWithFrac` | `f64`, `String`        |
 ///
 /// # Examples
 ///

serde_with/src/time_0_3.rs

@@ -1,3 +1,9 @@
+//! De/Serialization of [time v0.3][time] types
+//!
+//! This modules is only available if using the `time_0_3` feature of the crate.
+//!
+//! [time]: https://docs.rs/time/0.3/
+
 use crate::de::DeserializeAs;
 use crate::formats::{Flexible, Format, Strict, Strictness};
 use crate::ser::SerializeAs;