Add doctests

bouzuya · Dec 31, 2023 · 40a5c91 · 40a5c91
1 parent 2d7741e
commit 40a5c91
Show file tree

Hide file tree

Showing 2 changed files with 141 additions and 1 deletion.
diff --git a/src/with/chrono_date_time_as_timestamp.rs b/src/with/chrono_date_time_as_timestamp.rs
@@ -1,7 +1,38 @@
-//! (De)serialize `chrono::DateTime<Tz>` as `timestampValue`.
+//! (De)serialize `chrono::DateTime<chrono::Utc>` as `timestampValue`.
 
 use prost_types::Timestamp;
 
+/// Deserialize `chrono::DateTime<chrono::Utc>` from `timestampValue`.
+///
+/// # Examples
+///
+/// ```rust
+/// # fn main() -> anyhow::Result<()> {
+/// use google_api_proto::google::firestore::v1::{value::ValueType, Value};
+/// use prost_types::Timestamp;
+/// use serde_firestore_value::{from_value, with::chrono_date_time_as_timestamp};
+///
+/// #[derive(Debug, Eq, PartialEq, serde::Deserialize)]
+/// struct S(
+///     #[serde(deserialize_with = "chrono_date_time_as_timestamp::deserialize")]
+///     chrono::DateTime<chrono::Utc>,
+/// );
+///
+/// let o = S(chrono::DateTime::<chrono::FixedOffset>::parse_from_rfc3339(
+///     "1970-01-01T00:00:01.000000002Z",
+/// )?
+/// .with_timezone(&chrono::Utc));
+/// let v = Value {
+///     value_type: Some(ValueType::TimestampValue(Timestamp {
+///         seconds: 1_i64,
+///         nanos: 2_i32,
+///     })),
+/// };
+/// let d = from_value::<'_, S>(&v)?;
+/// assert_eq!(d, o);
+/// #     Ok(())
+/// # }
+/// ```
 pub fn deserialize<'de, D>(deserializer: D) -> Result<chrono::DateTime<chrono::Utc>, D::Error>
 where
     D: serde::Deserializer<'de>,
@@ -13,6 +44,37 @@ where
     ))
 }
 
+/// Serialize `chrono::DateTime<chrono::Utc>` as `timestampValue`.
+///
+/// # Examples
+///
+/// ```rust
+/// # fn main() -> anyhow::Result<()> {
+/// use google_api_proto::google::firestore::v1::{value::ValueType, Value};
+/// use prost_types::Timestamp;
+/// use serde_firestore_value::{to_value, with::chrono_date_time_as_timestamp};
+///
+/// #[derive(Debug, Eq, PartialEq, serde::Serialize)]
+/// struct S(
+///     #[serde(serialize_with = "chrono_date_time_as_timestamp::serialize")]
+///     chrono::DateTime<chrono::Utc>,
+/// );
+///
+/// let o = S(chrono::DateTime::<chrono::FixedOffset>::parse_from_rfc3339(
+///     "1970-01-01T00:00:01.000000002Z",
+/// )?
+/// .with_timezone(&chrono::Utc));
+/// let v = Value {
+///     value_type: Some(ValueType::TimestampValue(Timestamp {
+///         seconds: 1_i64,
+///         nanos: 2_i32,
+///     })),
+/// };
+/// let s = to_value(&o)?;
+/// assert_eq!(s, v);
+/// #     Ok(())
+/// # }
+/// ```
 pub fn serialize<S>(
     date_time: &chrono::DateTime<chrono::Utc>,
     serializer: S,

diff --git a/src/with/time_offset_date_time_as_timestamp.rs b/src/with/time_offset_date_time_as_timestamp.rs
@@ -2,6 +2,45 @@
 
 use prost_types::Timestamp;
 
+/// Deserialize `time::OffsetDateTime` from `timestampValue`.
+///
+/// # Examples
+///
+/// ```rust
+/// # fn main() -> anyhow::Result<()> {
+/// use google_api_proto::google::firestore::v1::{value::ValueType, Value};
+/// use prost_types::Timestamp;
+/// use serde_firestore_value::{
+///     from_value, with::option_time_offset_date_time_as_timestamp,
+/// };
+///
+/// #[derive(Debug, Eq, PartialEq, serde::Deserialize)]
+/// struct S(
+///     #[serde(deserialize_with = "option_time_offset_date_time_as_timestamp::deserialize")]
+///     Option<time::OffsetDateTime>,
+/// );
+///
+/// let o = S(Some(time::OffsetDateTime::from_unix_timestamp_nanos(
+///     1_000_000_002_i128,
+/// )?));
+/// let v = Value {
+///     value_type: Some(ValueType::TimestampValue(Timestamp {
+///         seconds: 1_i64,
+///         nanos: 2_i32,
+///     })),
+/// };
+/// let d = from_value::<'_, S>(&v)?;
+/// assert_eq!(d, o);
+///
+/// let o = S(None);
+/// let v = Value {
+///     value_type: Some(ValueType::NullValue(0)),
+/// };
+/// let d = from_value::<'_, S>(&v)?;
+/// assert_eq!(d, o);
+/// #     Ok(())
+/// # }
+/// ```
 pub fn deserialize<'de, D>(deserializer: D) -> Result<time::OffsetDateTime, D::Error>
 where
     D: serde::Deserializer<'de>,
@@ -13,6 +52,45 @@ where
     .expect("timestamp"))
 }
 
+/// Serialize `time::OffsetDateTime` as `timestampValue`.
+///
+/// # Examples
+///
+/// ```rust
+/// # fn main() -> anyhow::Result<()> {
+/// use google_api_proto::google::firestore::v1::{value::ValueType, Value};
+/// use prost_types::Timestamp;
+/// use serde_firestore_value::{
+///     to_value, with::option_time_offset_date_time_as_timestamp,
+/// };
+///
+/// #[derive(Debug, Eq, PartialEq, serde::Serialize)]
+/// struct S(
+///     #[serde(serialize_with = "option_time_offset_date_time_as_timestamp::serialize")]
+///     Option<time::OffsetDateTime>,
+/// );
+///
+/// let o = S(Some(time::OffsetDateTime::from_unix_timestamp_nanos(
+///     1_000_000_002_i128,
+/// )?));
+/// let v = Value {
+///     value_type: Some(ValueType::TimestampValue(Timestamp {
+///         seconds: 1_i64,
+///         nanos: 2_i32,
+///     })),
+/// };
+/// let s = to_value(&o)?;
+/// assert_eq!(s, v);
+///
+/// let o = S(None);
+/// let v = Value {
+///     value_type: Some(ValueType::NullValue(0)),
+/// };
+/// let s = to_value(&o)?;
+/// assert_eq!(s, v);
+/// #     Ok(())
+/// # }
+/// ```
 pub fn serialize<S>(
     offset_date_time: &time::OffsetDateTime,
     serializer: S,