From 3c058086e2d7a0f2603b45d7cfea73abaf1f8e50 Mon Sep 17 00:00:00 2001 From: Brandon W Maister Date: Wed, 21 Jun 2017 12:49:31 -0500 Subject: [PATCH] Update serde docs --- src/datetime.rs | 65 ++++++++++++++++++++++--------------------- src/lib.rs | 17 +++++++++-- src/naive/datetime.rs | 6 ++-- 3 files changed, 51 insertions(+), 37 deletions(-) diff --git a/src/datetime.rs b/src/datetime.rs index e8dd6c1..50d0830 100644 --- a/src/datetime.rs +++ b/src/datetime.rs @@ -634,15 +634,12 @@ mod rustc_serialize { } -/// Ser/de helpers -/// -/// The various modules in here are intended to be used with serde's [`with` -/// annotation](https://serde.rs/attributes.html#field-attributes). +/// documented at re-export site #[cfg(feature = "serde")] pub mod serde { use std::fmt; use super::DateTime; - use offset::{TimeZone, LocalResult, Utc, Local, FixedOffset}; + use offset::{TimeZone, Utc, Local, FixedOffset}; use serdelib::{ser, de}; /// Ser/de to/from timestamps in seconds @@ -686,8 +683,7 @@ pub mod serde { use serdelib::{ser, de}; use {DateTime, Utc, FixedOffset}; - use offset::TimeZone; - use super::from; + use offset::{LocalResult, TimeZone}; /// Deserialize a DateTime from a seconds timestamp /// @@ -786,11 +782,28 @@ pub mod serde { } } + // try!-like function to convert a LocalResult into a serde-ish Result + fn from(me: LocalResult, ts: V) -> Result + where E: de::Error, + V: fmt::Display, + T: fmt::Display, + { + match me { + LocalResult::None => Err(E::custom( + format!("value is not a legal timestamp: {}", ts))), + LocalResult::Ambiguous(min, max) => Err(E::custom( + format!("value is an ambiguous timestamp: {}, could be either of {}, {}", + ts, min, max))), + LocalResult::Single(val) => Ok(val) + } + } } - // TODO not very optimized for space (binary formats would want something better) - impl ser::Serialize for DateTime { + /// Serialize into a rfc3339 time string + /// + /// See [the `serde` module](./serde/index.html) for alternate + /// serializations. fn serialize(&self, serializer: S) -> Result where S: ser::Serializer { @@ -809,22 +822,6 @@ pub mod serde { } } - // try!-like function to convert a LocalResult into a serde-ish Result - fn from(me: LocalResult, ts: V) -> Result - where E: de::Error, - V: fmt::Display, - T: fmt::Display, - { - match me { - LocalResult::None => Err(E::custom( - format!("value is not a legal timestamp: {}", ts))), - LocalResult::Ambiguous(min, max) => Err(E::custom( - format!("value is an ambiguous timestamp: {}, could be either of {}, {}", - ts, min, max))), - LocalResult::Single(val) => Ok(val) - } - } - struct DateTimeVisitor; impl<'de> de::Visitor<'de> for DateTimeVisitor { @@ -845,8 +842,10 @@ pub mod serde { /// Deserialize a value that optionally includes a timezone offset in its /// string representation /// - /// The serialized value can be either a string representation or a unix - /// timestamp + /// The value to be deserialized must be an rfc3339 string. + /// + /// See [the `serde` module](./serde/index.html) for alternate + /// deserialization formats. impl<'de> de::Deserialize<'de> for DateTime { fn deserialize(deserializer: D) -> Result where D: de::Deserializer<'de> @@ -857,8 +856,10 @@ pub mod serde { /// Deserialize into a UTC value /// - /// The serialized value can be either a string representation or a unix - /// timestamp + /// The value to be deserialized must be an rfc3339 string. + /// + /// See [the `serde` module](./serde/index.html) for alternate + /// deserialization formats. impl<'de> de::Deserialize<'de> for DateTime { fn deserialize(deserializer: D) -> Result where D: de::Deserializer<'de> @@ -870,8 +871,10 @@ pub mod serde { /// Deserialize a value that includes no timezone in its string /// representation /// - /// The serialized value can be either a string representation or a unix - /// timestamp + /// The value to be deserialized must be an rfc3339 string. + /// + /// See [the `serde` module](./serde/index.html) for alternate + /// serialization formats. impl<'de> de::Deserialize<'de> for DateTime { fn deserialize(deserializer: D) -> Result where D: de::Deserializer<'de> diff --git a/src/lib.rs b/src/lib.rs index 2606e43..c4a70f8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -412,7 +412,14 @@ pub mod naive { pub use self::time::NaiveTime; pub use self::datetime::{NaiveDateTime, TsSeconds}; - /// Tools to help serializing/deserializing naive types. + /// Serialization/Deserialization of naive types in alternate formats + /// + /// The various modules in here are intended to be used with serde's [`with` + /// annotation][1] to serialize as something other than the default [RFC + /// 3339][2] format. + /// + /// [1]: https://serde.rs/attributes.html#field-attributes + /// [2]: https://tools.ietf.org/html/rfc3339 #[cfg(feature = "serde")] pub mod serde { pub use super::datetime::serde::*; @@ -422,10 +429,14 @@ mod date; mod datetime; pub mod format; -/// Ser/de helpers +/// Serialization/Deserialization in alternate formats /// /// The various modules in here are intended to be used with serde's [`with` -/// annotation](https://serde.rs/attributes.html#field-attributes). +/// annotation][1] to serialize as something other than the default [RFC +/// 3339][2] format. +/// +/// [1]: https://serde.rs/attributes.html#field-attributes +/// [2]: https://tools.ietf.org/html/rfc3339 #[cfg(feature = "serde")] pub mod serde { pub use super::datetime::serde::*; diff --git a/src/naive/datetime.rs b/src/naive/datetime.rs index 28d470c..4758be4 100644 --- a/src/naive/datetime.rs +++ b/src/naive/datetime.rs @@ -1525,10 +1525,10 @@ pub mod serde { use super::{NaiveDateTime}; use serdelib::{ser, de}; - /// Serialize a NaiveDateTime as a string + /// Serialize a NaiveDateTime as an RFC 3339 string /// - /// See the [`ts_seconds`](./serde/ts_seconds/index.html) module to serialize as - /// a timestamp. + /// See [the `serde` module](./serde/index.html) for alternate + /// serialization formats. impl ser::Serialize for NaiveDateTime { fn serialize(&self, serializer: S) -> Result where S: ser::Serializer