diff --git a/serde/src/buf.rs b/serde/src/buf.rs index 4dd41aaf..42b9185f 100644 --- a/serde/src/buf.rs +++ b/serde/src/buf.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::cmp; use std::io; use std::slice; diff --git a/serde/src/bytes.rs b/serde/src/bytes.rs index b3e02711..1e58cd62 100644 --- a/serde/src/bytes.rs +++ b/serde/src/bytes.rs @@ -1,5 +1,7 @@ //! Helper module to enable serializing bytes more efficiently +#![allow(missing_docs)] + use std::ops; use std::fmt; use std::ascii; diff --git a/serde/src/de/impls.rs b/serde/src/de/impls.rs index b9543c83..3fbce9b0 100644 --- a/serde/src/de/impls.rs +++ b/serde/src/de/impls.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::borrow::Cow; use std::collections::{ BinaryHeap, diff --git a/serde/src/de/mod.rs b/serde/src/de/mod.rs index 2be58104..222e3f84 100644 --- a/serde/src/de/mod.rs +++ b/serde/src/de/mod.rs @@ -1,5 +1,7 @@ //! Generic deserialization framework. +#![allow(missing_docs)] + pub mod impls; pub mod value; diff --git a/serde/src/de/value.rs b/serde/src/de/value.rs index af0716be..e529735e 100644 --- a/serde/src/de/value.rs +++ b/serde/src/de/value.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::collections::{ BTreeMap, BTreeSet, diff --git a/serde/src/iter.rs b/serde/src/iter.rs index ec0bb134..aa906666 100644 --- a/serde/src/iter.rs +++ b/serde/src/iter.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::io; use std::iter::Peekable; diff --git a/serde/src/lib.rs b/serde/src/lib.rs index d120f130..e6b8528f 100644 --- a/serde/src/lib.rs +++ b/serde/src/lib.rs @@ -5,9 +5,12 @@ //! handshake protocol between serializers and serializees can be completely optimized away, //! leaving serde to perform roughly the same speed as a hand written serializer for a specific //! type. + #![doc(html_root_url="https://serde-rs.github.io/serde/serde")] #![cfg_attr(feature = "nightly", feature(collections, core, enumset, nonzero, step_trait, zero_one))] +#![deny(missing_docs)] + extern crate num; #[cfg(feature = "nightly")] diff --git a/serde/src/ser/impls.rs b/serde/src/ser/impls.rs index 8a31b4af..1d21ec71 100644 --- a/serde/src/ser/impls.rs +++ b/serde/src/ser/impls.rs @@ -1,3 +1,5 @@ +#![allow(missing_docs)] + use std::borrow::Cow; use std::collections::{ BinaryHeap, diff --git a/serde/src/ser/mod.rs b/serde/src/ser/mod.rs index 3971495c..b07e654a 100644 --- a/serde/src/ser/mod.rs +++ b/serde/src/ser/mod.rs @@ -4,14 +4,18 @@ pub mod impls; /////////////////////////////////////////////////////////////////////////////// +/// A trait that describes a type that can be serialized by a `Serializer`. pub trait Serialize { + /// Serializes this value into this serializer. fn serialize(&self, serializer: &mut S) -> Result<(), S::Error> where S: Serializer; } /////////////////////////////////////////////////////////////////////////////// +/// A trait that describes a type that can serialize a stream of values into the underlying format. pub trait Serializer { + /// The error type that can be returned if some error occurs during serialization. type Error; /// `visit_bool` serializes a `bool` value. @@ -110,13 +114,20 @@ pub trait Serializer { self.visit_seq(impls::SeqIteratorVisitor::new(value.iter(), Some(value.len()))) } + /// Serializes a `()` value. fn visit_unit(&mut self) -> Result<(), Self::Error>; + /// Serializes a unit struct value. + /// + /// By default, unit structs are serialized as a `()`. #[inline] fn visit_unit_struct(&mut self, _name: &'static str) -> Result<(), Self::Error> { self.visit_unit() } + /// Serializes a unit variant, otherwise known as a variant with no arguments. + /// + /// By default, unit variants are serialized as a `()`. #[inline] fn visit_unit_variant(&mut self, _name: &'static str, @@ -155,17 +166,27 @@ pub trait Serializer { Some(value)) } + /// Serializes a `None` value. fn visit_none(&mut self) -> Result<(), Self::Error>; + /// Serializes a `Some(...)` value. fn visit_some(&mut self, value: V) -> Result<(), Self::Error> where V: Serialize; + /// Serializes a sequence. + /// + /// Callees of this method need to construct a `SeqVisitor`, which iterates through each item + /// in the sequence. fn visit_seq(&mut self, visitor: V) -> Result<(), Self::Error> where V: SeqVisitor; + /// Serializes a sequence element. fn visit_seq_elt(&mut self, value: T) -> Result<(), Self::Error> where T: Serialize; + /// Serializes a tuple. + /// + /// By default this serializes a tuple as a sequence. #[inline] fn visit_tuple(&mut self, visitor: V) -> Result<(), Self::Error> where V: SeqVisitor, @@ -173,6 +194,9 @@ pub trait Serializer { self.visit_seq(visitor) } + /// Serializes a tuple element. + /// + /// By default, tuples are serialized as a sequence. #[inline] fn visit_tuple_elt(&mut self, value: T) -> Result<(), Self::Error> where T: Serialize @@ -180,6 +204,9 @@ pub trait Serializer { self.visit_seq_elt(value) } + /// Serializes a tuple struct. + /// + /// By default, tuple structs are serialized as a tuple. #[inline] fn visit_tuple_struct(&mut self, _name: &'static str, @@ -189,6 +216,9 @@ pub trait Serializer { self.visit_tuple(visitor) } + /// Serializes a tuple struct element. + /// + /// By default, tuple struct elements are serialized as a tuple element. #[inline] fn visit_tuple_struct_elt(&mut self, value: T) -> Result<(), Self::Error> where T: Serialize @@ -196,6 +226,9 @@ pub trait Serializer { self.visit_tuple_elt(value) } + /// Serializes a tuple variant. + /// + /// By default, tuple variants are serialized as a tuple struct. #[inline] fn visit_tuple_variant(&mut self, _name: &'static str, @@ -207,6 +240,9 @@ pub trait Serializer { self.visit_tuple_struct(variant, visitor) } + /// Serializes a tuple element. + /// + /// By default, tuples are serialized as a sequence. #[inline] fn visit_tuple_variant_elt(&mut self, value: T) -> Result<(), Self::Error> where T: Serialize @@ -214,13 +250,21 @@ pub trait Serializer { self.visit_tuple_struct_elt(value) } + /// Serializes a map. + /// + /// Callees of this method need to construct a `MapVisitor`, which iterates through each item + /// in the map. fn visit_map(&mut self, visitor: V) -> Result<(), Self::Error> where V: MapVisitor; + /// Serializes a map element (key-value pair). fn visit_map_elt(&mut self, key: K, value: V) -> Result<(), Self::Error> where K: Serialize, V: Serialize; + /// Serializes a struct. + /// + /// By default, structs are serialized as a map with the field name as the key. #[inline] fn visit_struct(&mut self, _name: &'static str, @@ -230,6 +274,9 @@ pub trait Serializer { self.visit_map(visitor) } + /// Serializes an element of a struct. + /// + /// By default, struct elements are serialized as a map element with the field name as the key. #[inline] fn visit_struct_elt(&mut self, key: &'static str, @@ -239,6 +286,9 @@ pub trait Serializer { self.visit_map_elt(key, value) } + /// Serializes a struct variant. + /// + /// By default, struct variants are serialized as a struct. #[inline] fn visit_struct_variant(&mut self, _name: &'static str, @@ -250,6 +300,9 @@ pub trait Serializer { self.visit_struct(variant, visitor) } + /// Serializes an element of a struct variant. + /// + /// By default, struct variant elements are serialized as a struct element. #[inline] fn visit_struct_variant_elt(&mut self, key: &'static str, @@ -268,7 +321,12 @@ pub trait Serializer { } } +/// A trait that is used by a `Serialize` to iterate through a sequence. pub trait SeqVisitor { + /// Serializes a sequence item in the serializer. + /// + /// This returns `Ok(Some(()))` when there are more items to serialize, or `Ok(None)` when + /// complete. fn visit(&mut self, serializer: &mut S) -> Result, S::Error> where S: Serializer; @@ -279,7 +337,12 @@ pub trait SeqVisitor { } } +/// A trait that is used by a `Serializer` to iterate through a map. pub trait MapVisitor { + /// Serializes a map item in the serializer. + /// + /// This returns `Ok(Some(()))` when there are more items to serialize, or `Ok(None)` when + /// complete. fn visit(&mut self, serializer: &mut S) -> Result, S::Error> where S: Serializer;