RUST-1748 Refactor BSON DateTime serde converters using serde_conv_doc macro (#570)

Author: JamieTsai1024

README.md

@@ -230,7 +230,7 @@ provides a `DateTime` type, but its `Serialize` and `Deserialize` implementation
 instead, so when using it with BSON, the BSON datetime type is not used. To work around this, the
 `chrono-0_4` feature flag can be enabled. This flag exposes a number of convenient conversions
 between `bson::DateTime` and `chrono::DateTime`, including the
-[`bson_datetime::FromChronoDateTime`](https://docs.rs/bson/latest/bson/serde_helpers/bson_datetime/struct.FromChronoDateTime/index.html)
+[`datetime::FromChrono04DateTime`](https://docs.rs/bson/latest/bson/serde_helpers/datetime/struct.FromChrono04DateTime/index.html)
 serde helper, which can be used to (de)serialize `chrono::DateTime`s to/from BSON datetimes, and the
 `From<chrono::DateTime>` implementation for `Bson`, which allows `chrono::DateTime` values to be
 used in the `doc!` and `bson!` macros.
@@ -251,7 +251,7 @@ struct Foo {
 
     // serializes as a BSON datetime.
     // this requires the "chrono-0_4" feature flag
-    #[serde_as(as = "bson::serde_helpers::bson_datetime::FromChronoDateTime")]
+    #[serde_as(as = "bson::serde_helpers::datetime::FromChrono04DateTime")]
     chrono_as_bson: chrono::DateTime<chrono::Utc>,
 }
 

src/datetime.rs

@@ -108,20 +108,25 @@ use crate::error::{Error, Result};
 ///
 /// ### `serde_helpers`
 /// The `bson` crate provides a number of useful helpers for serializing and deserializing
-/// various datetime types to and from different formats. For example, to serialize a
-/// [`chrono::DateTime`] as a BSON datetime, you can use
-/// [`crate::serde_helpers::bson_datetime::FromChronoDateTime`].
-/// Similarly, to serialize a BSON [`DateTime`] to a string, you can use
-/// [`crate::serde_helpers::bson_datetime::AsRfc3339String`]. Check out the
-/// [`crate::serde_helpers`] module documentation for a list of all of the helpers offered by the
+/// various datetime types to and from different formats using the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/)
 /// crate.
 ///
+/// > **Note:** All helpers in this module require use of the [`#[serde_as]`](https://docs.rs/serde_with/latest/serde_with/attr.serde_as.html)
+/// > attribute on the struct. This enables the enhanced serialization behavior provided by
+/// > `serde_with-3`.
+///
+/// For example, to serialize a [`chrono::DateTime`] as a BSON datetime, you can use
+/// [`crate::serde_helpers::datetime::FromChrono04DateTime`].
+/// Similarly, to serialize a BSON [`DateTime`] to a string, you can use
+/// [`crate::serde_helpers::datetime::AsRfc3339String`]. Check out the
+/// [`crate::serde_helpers`] module documentation for a list of all of the helpers
+/// offered by the crate.
 /// ```rust
-/// # #[cfg(feature = "chrono-0_4")]
+/// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
 /// # {
 /// use serde::{Serialize, Deserialize};
 /// use serde_with::serde_as;
-/// use bson::serde_helpers::bson_datetime;
+/// use bson::serde_helpers::datetime;
 ///
 /// #[serde_as]
 /// #[derive(Serialize, Deserialize)]
@@ -134,33 +139,30 @@ use crate::error::{Error, Result};
 ///
 ///     // serializes as a BSON datetime.
 ///     // this requires the "chrono-0_4" feature flag
-///     #[serde_as(as = "bson_datetime::FromChronoDateTime")]
+///     #[serde_as(as = "datetime::FromChrono04DateTime")]
 ///     chrono_as_bson: chrono::DateTime<chrono::Utc>,
 ///
 ///     // serializes as an RFC 3339 / ISO-8601 string.
-///     #[serde_as(as = "bson_datetime::AsRfc3339String")]
+///     // this requires the "serde_with-3" feature flag
+///     #[serde_as(as = "datetime::AsRfc3339String")]
 ///     bson_as_string: bson::DateTime,
 /// }
 /// # }
 /// ```
-/// ### The `serde_with-3` feature flag
-///
-/// The `serde_with-3` feature can be enabled to support more ergonomic serde attributes for
-/// (de)serializing [`chrono::DateTime`] from/to BSON via the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/)
-/// crate. The main benefit of this compared to the regular `serde_helpers` is that `serde_with-3`
-/// can handle nested [`chrono::DateTime`] values (e.g. in [`Option`]), whereas the former only
-/// works on fields that are exactly [`chrono::DateTime`].
+/// The main benefit of using the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/) crate
+/// is that it can handle nested [`chrono::DateTime`] values (e.g. in [`Option`] or [`Vec`]).
 /// ```
 /// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
 /// # {
 /// use serde::{Deserialize, Serialize};
-/// use bson::doc;
+/// use serde_with::serde_as;
+/// use bson::{doc, serde_helpers::datetime};
 ///
-/// #[serde_with::serde_as]
+/// #[serde_as]
 /// #[derive(Deserialize, Serialize, PartialEq, Debug)]
 /// struct Foo {
-///   /// Serializes as a BSON datetime rather than using [`chrono::DateTime`]'s serialization
-///   #[serde_as(as = "Option<bson::DateTime>")]
+///   /// serializes as a BSON datetime rather than using [`chrono::DateTime`]'s serialization
+///   #[serde_as(as = "Option<datetime::FromChrono04DateTime>")]
 ///   as_bson: Option<chrono::DateTime<chrono::Utc>>,
 /// }
 ///

src/lib.rs

@@ -322,7 +322,7 @@
 //! on strings instead, so when using it with BSON, the BSON datetime type is not used. To work
 //! around this, the `chrono-0_4` feature flag can be enabled. This flag exposes a number of
 //! convenient conversions between [`bson::DateTime`](crate::DateTime) and [`chrono::DateTime`],
-//! including the [`serde_helpers::bson_datetime::FromChronoDateTime`]
+//! including the [`serde_helpers::datetime::FromChrono04DateTime`]
 //! serde helper, which can be used to (de)serialize [`chrono::DateTime`]s to/from BSON datetimes,
 //! and the `From<chrono::DateTime>` implementation for [`Bson`], which allows [`chrono::DateTime`]
 //! values to be used in the `doc!` and `bson!` macros.
@@ -334,7 +334,7 @@
 //! use serde::{Serialize, Deserialize};
 //! use serde_with::serde_as;
 //! use bson::doc;
-//! use bson::serde_helpers::bson_datetime;
+//! use bson::serde_helpers::datetime;
 //!
 //! #[serde_as]
 //! #[derive(Serialize, Deserialize)]
@@ -347,7 +347,7 @@
 //!
 //!     // serializes as a BSON datetime.
 //!     // this requires the "chrono-0_4" feature flag
-//!     #[serde_as(as = "bson_datetime::FromChronoDateTime")]
+//!     #[serde_as(as = "datetime::FromChrono04DateTime")]
 //!     chrono_as_bson: chrono::DateTime<chrono::Utc>,
 //! }
 //!