From fdaa8202b945733daf0397e381367642d8437505 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Fri, 7 Apr 2017 11:06:19 -0700 Subject: [PATCH] Clean up some existing examples --- serde/src/de/mod.rs | 131 ++++++++++++++++++++++++++----------------- serde/src/macros.rs | 25 +++++++-- serde/src/ser/mod.rs | 26 +++++++-- 3 files changed, 119 insertions(+), 63 deletions(-) diff --git a/serde/src/de/mod.rs b/serde/src/de/mod.rs index 9a6130ab..453a531b 100644 --- a/serde/src/de/mod.rs +++ b/serde/src/de/mod.rs @@ -139,20 +139,26 @@ macro_rules! declare_error_trait { /// The message should not be capitalized and should not end with a period. /// /// ```rust - /// # use serde::de::{Deserialize, Deserializer, Error}; /// # use std::str::FromStr; - /// # #[allow(dead_code)] + /// # /// # struct IpAddr; + /// # /// # impl FromStr for IpAddr { /// # type Err = String; - /// # fn from_str(_: &str) -> Result { unimplemented!() } + /// # + /// # fn from_str(_: &str) -> Result { + /// # unimplemented!() + /// # } /// # } + /// # + /// use serde::de::{self, Deserialize, Deserializer}; + /// /// impl<'de> Deserialize<'de> for IpAddr { /// fn deserialize(deserializer: D) -> Result /// where D: Deserializer<'de> /// { /// let s = try!(String::deserialize(deserializer)); - /// s.parse().map_err(Error::custom) + /// s.parse().map_err(de::Error::custom) /// } /// } /// ``` @@ -260,20 +266,24 @@ declare_error_trait!(Error: Sized + Debug + Display); /// `invalid_length` methods of the `Error` trait to build error messages. /// /// ```rust -/// # use serde::de::{Error, Unexpected, Visitor}; /// # use std::fmt; -/// # #[allow(dead_code)] +/// # +/// # use serde::de::{self, Unexpected, Visitor}; +/// # /// # struct Example; +/// # /// # impl<'de> Visitor<'de> for Example { -/// # type Value = (); +/// # type Value = (); +/// # +/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { +/// # write!(formatter, "definitely not a boolean") +/// # } +/// # /// fn visit_bool(self, v: bool) -> Result -/// where E: Error +/// where E: de::Error /// { -/// Err(Error::invalid_type(Unexpected::Bool(v), &self)) +/// Err(de::Error::invalid_type(Unexpected::Bool(v), &self)) /// } -/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { -/// # write!(formatter, "definitely not a boolean") -/// # } /// # } /// ``` #[derive(Clone, PartialEq, Debug)] @@ -380,31 +390,37 @@ impl<'a> fmt::Display for Unexpected<'a> { /// (`&self`) is an implementation of this trait. /// /// ```rust -/// # use serde::de::{Error, Unexpected, Visitor}; /// # use std::fmt; -/// # #[allow(dead_code)] +/// # +/// # use serde::de::{self, Unexpected, Visitor}; +/// # /// # struct Example; +/// # /// # impl<'de> Visitor<'de> for Example { -/// # type Value = (); +/// # type Value = (); +/// # +/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { +/// # write!(formatter, "definitely not a boolean") +/// # } +/// # /// fn visit_bool(self, v: bool) -> Result -/// where E: Error +/// where E: de::Error /// { -/// Err(Error::invalid_type(Unexpected::Bool(v), &self)) +/// Err(de::Error::invalid_type(Unexpected::Bool(v), &self)) /// } -/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { -/// # write!(formatter, "definitely not a boolean") -/// # } /// # } /// ``` /// /// Outside of a `Visitor`, `&"..."` can be used. /// /// ```rust -/// # use serde::de::{Error, Unexpected}; -/// # #[allow(dead_code)] -/// # fn example() -> Result<(), E> { -/// # let v = true; -/// return Err(Error::invalid_type(Unexpected::Bool(v), &"a negative integer")); +/// # use serde::de::{self, Unexpected}; +/// # +/// # fn example() -> Result<(), E> +/// # where E: de::Error +/// # { +/// # let v = true; +/// return Err(de::Error::invalid_type(Unexpected::Bool(v), &"a negative integer")); /// # } /// ``` pub trait Expected { @@ -509,11 +525,13 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// /// ```rust /// # use serde::Deserialize; -/// # #[allow(dead_code)] +/// # /// # enum Error {} -/// # #[allow(dead_code)] +/// # /// fn func<'de, T: Deserialize<'de>>() -> Result -/// # { unimplemented!() } +/// # { +/// # unimplemented!() +/// # } /// ``` /// /// Adjusting an API like this to support stateful deserialization is a matter @@ -521,9 +539,9 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// /// ```rust /// # use serde::de::DeserializeSeed; -/// # #[allow(dead_code)] +/// # /// # enum Error {} -/// # #[allow(dead_code)] +/// # /// fn func_seed<'de, T: DeserializeSeed<'de>>(seed: T) -> Result /// # { /// # let _ = seed; @@ -545,10 +563,11 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// trait. /// /// ```rust -/// # use serde::de::{Deserialize, DeserializeSeed, Deserializer, Visitor, SeqVisitor}; -/// # use std::fmt; -/// # use std::marker::PhantomData; -/// # +/// use std::fmt; +/// use std::marker::PhantomData; +/// +/// use serde::de::{Deserialize, DeserializeSeed, Deserializer, Visitor, SeqVisitor}; +/// /// // A DeserializeSeed implementation that uses stateful deserialization to /// // append array elements onto the end of an existing vector. The preexisting /// // state ("seed") in this case is the Vec. The `deserialize` method of @@ -576,6 +595,10 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// { /// type Value = (); /// +/// fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { +/// write!(formatter, "an array of integers") +/// } +/// /// fn visit_seq(self, mut visitor: V) -> Result<(), V::Error> /// where V: SeqVisitor<'de> /// { @@ -586,10 +609,6 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// } /// Ok(()) /// } -/// # -/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { -/// # write!(formatter, "an array of integers") -/// # } /// } /// /// deserializer.deserialize_seq(ExtendVecVisitor(self.0)) @@ -606,6 +625,10 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// // contents of the inner arrays. /// type Value = Vec; /// +/// fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { +/// write!(formatter, "an array of arrays") +/// } +/// /// fn visit_seq(self, mut visitor: V) -> Result, V::Error> /// where V: SeqVisitor<'de> /// { @@ -620,18 +643,15 @@ impl DeserializeOwned for T where T: for<'de> Deserialize<'de> {} /// // Return the finished vec. /// Ok(vec) /// } -/// # -/// # fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { -/// # write!(formatter, "an array of arrays") -/// # } /// } /// -/// # #[allow(dead_code)] -/// # fn example<'de, D: Deserializer<'de>>(deserializer: D) -> Result<(), D::Error> { +/// # fn example<'de, D>(deserializer: D) -> Result<(), D::Error> +/// # where D: Deserializer<'de> +/// # { /// let visitor = FlattenedVecVisitor(PhantomData); /// let flattened: Vec = deserializer.deserialize_seq(visitor)?; -/// # let _ = flattened; -/// # Ok(()) } +/// # Ok(()) +/// # } /// ``` pub trait DeserializeSeed<'de>: Sized { /// The type produced by using this seed. @@ -917,11 +937,12 @@ pub trait Deserializer<'de>: Sized { /// This trait represents a visitor that walks through a deserializer. /// /// ```rust -/// # use serde::de::{Error, Unexpected, Visitor}; /// # use std::fmt; +/// # +/// # use serde::de::{self, Unexpected, Visitor}; +/// # /// /// A visitor that deserializes a long string - a string containing at least /// /// some minimum number of bytes. -/// # #[allow(dead_code)] /// struct LongString { /// min: usize, /// } @@ -934,12 +955,12 @@ pub trait Deserializer<'de>: Sized { /// } /// /// fn visit_str(self, s: &str) -> Result -/// where E: Error +/// where E: de::Error /// { /// if s.len() >= self.min { /// Ok(s.to_owned()) /// } else { -/// Err(Error::invalid_value(Unexpected::Str(s), &self)) +/// Err(de::Error::invalid_value(Unexpected::Str(s), &self)) /// } /// } /// } @@ -957,10 +978,14 @@ pub trait Visitor<'de>: Sized { /// /// ```rust /// # use std::fmt; - /// # #[allow(dead_code)] - /// # struct S { max: usize } + /// # + /// # struct S { + /// # max: usize, + /// # } + /// # /// # impl<'de> serde::de::Visitor<'de> for S { - /// # type Value = (); + /// # type Value = (); + /// # /// fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result { /// write!(formatter, "an integer between 0 and {}", self.max) /// } diff --git a/serde/src/macros.rs b/serde/src/macros.rs index 022e1214..5873e1a7 100644 --- a/serde/src/macros.rs +++ b/serde/src/macros.rs @@ -117,14 +117,21 @@ macro_rules! forward_to_deserialize_helper { /// methods. /// /// ```rust -/// # #[macro_use] extern crate serde; +/// # #[macro_use] +/// # extern crate serde; +/// # /// # use serde::de::{value, Deserializer, Visitor}; -/// # pub struct MyDeserializer; +/// # +/// # struct MyDeserializer; +/// # /// # impl<'de> Deserializer<'de> for MyDeserializer { /// # type Error = value::Error; +/// # /// # fn deserialize(self, _: V) -> Result /// # where V: Visitor<'de> -/// # { unimplemented!() } +/// # { +/// # unimplemented!() +/// # } /// # /// #[inline] /// fn deserialize_bool(self, visitor: V) -> Result @@ -132,12 +139,14 @@ macro_rules! forward_to_deserialize_helper { /// { /// self.deserialize(visitor) /// } +/// # /// # forward_to_deserialize! { /// # u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 char str string unit option /// # seq seq_fixed_size bytes byte_buf map unit_struct newtype_struct /// # tuple_struct struct struct_field tuple enum ignored_any /// # } /// # } +/// # /// # fn main() {} /// ``` /// @@ -146,11 +155,16 @@ macro_rules! forward_to_deserialize_helper { /// can choose which methods to forward. /// /// ```rust -/// # #[macro_use] extern crate serde; +/// # #[macro_use] +/// # extern crate serde; +/// # /// # use serde::de::{value, Deserializer, Visitor}; -/// # pub struct MyDeserializer; +/// # +/// # struct MyDeserializer; +/// # /// impl<'de> Deserializer<'de> for MyDeserializer { /// # type Error = value::Error; +/// # /// fn deserialize(self, visitor: V) -> Result /// where V: Visitor<'de> /// { @@ -165,6 +179,7 @@ macro_rules! forward_to_deserialize_helper { /// tuple_struct struct struct_field tuple enum ignored_any /// } /// } +/// # /// # fn main() {} /// ``` /// diff --git a/serde/src/ser/mod.rs b/serde/src/ser/mod.rs index 12e294f5..332bdfab 100644 --- a/serde/src/ser/mod.rs +++ b/serde/src/ser/mod.rs @@ -127,16 +127,23 @@ macro_rules! declare_error_trait { /// if it contains invalid UTF-8 data. /// /// ```rust - /// # use serde::ser::{Serialize, Serializer, Error}; /// # struct Path; - /// # impl Path { fn to_str(&self) -> Option<&str> { unimplemented!() } } + /// # + /// # impl Path { + /// # fn to_str(&self) -> Option<&str> { + /// # unimplemented!() + /// # } + /// # } + /// # + /// use serde::ser::{self, Serialize, Serializer}; + /// /// impl Serialize for Path { /// fn serialize(&self, serializer: S) -> Result /// where S: Serializer /// { /// match self.to_str() { /// Some(s) => s.serialize(serializer), - /// None => Err(Error::custom("path contains invalid UTF-8 characters")), + /// None => Err(ser::Error::custom("path contains invalid UTF-8 characters")), /// } /// } /// } @@ -524,6 +531,7 @@ pub trait Serializer: Sized { /// # impl<'a, T> IntoIterator for &'a Vec { /// # type Item = &'a T; /// # type IntoIter = Box>; + /// # /// # fn into_iter(self) -> Self::IntoIter { /// # unimplemented!() /// # } @@ -704,6 +712,7 @@ pub trait Serializer: Sized { /// # impl<'a, K, V> IntoIterator for &'a HashMap { /// # type Item = (&'a K, &'a V); /// # type IntoIter = Box>; + /// # /// # fn into_iter(self) -> Self::IntoIter { /// # unimplemented!() /// # } @@ -844,12 +853,15 @@ pub trait Serializer: Sized { /// more efficient implementation if possible. /// /// ```rust - /// # use serde::{Serialize, Serializer}; /// # struct DateTime; + /// # /// # impl DateTime { /// # fn naive_local(&self) -> () { () } /// # fn offset(&self) -> () { () } /// # } + /// # + /// use serde::{Serialize, Serializer}; + /// /// impl Serialize for DateTime { /// fn serialize(&self, serializer: S) -> Result /// where S: Serializer @@ -876,12 +888,15 @@ pub trait Serializer: Sized { /// implementation is expected to return an error. /// /// ```rust - /// # use serde::{Serialize, Serializer}; /// # struct DateTime; + /// # /// # impl DateTime { /// # fn naive_local(&self) -> () { () } /// # fn offset(&self) -> () { () } /// # } + /// # + /// use serde::{Serialize, Serializer}; + /// /// impl Serialize for DateTime { /// fn serialize(&self, serializer: S) -> Result /// where S: Serializer @@ -1118,6 +1133,7 @@ pub trait SerializeTupleVariant { /// # impl<'a, K, V> IntoIterator for &'a HashMap { /// # type Item = (&'a K, &'a V); /// # type IntoIter = Box>; +/// # /// # fn into_iter(self) -> Self::IntoIter { /// # unimplemented!() /// # }