Merge pull request #794 from clarcharr/master

Documentation for serde_test.

serde_test/src/assert.rs

@@ -7,6 +7,7 @@ use token::Token;
 
 use std::fmt::Debug;
 
+/// Runs both `assert_ser_tokens` and `assert_de_tokens`.
 pub fn assert_tokens<T>(value: &T, tokens: &[Token<'static>])
     where T: Serialize + Deserialize + PartialEq + Debug
 {
@@ -14,6 +15,7 @@ pub fn assert_tokens<T>(value: &T, tokens: &[Token<'static>])
     assert_de_tokens(value, tokens);
 }
 
+/// Asserts that `value` serializes to the given `tokens`.
 pub fn assert_ser_tokens<T>(value: &T, tokens: &[Token])
     where T: Serialize
 {
@@ -22,7 +24,7 @@ pub fn assert_ser_tokens<T>(value: &T, tokens: &[Token])
     assert_eq!(ser.next_token(), None);
 }
 
-/// Expect an error serializing `T`.
+/// Asserts that `value` serializes to the given `tokens`, and then yields `error`.
 pub fn assert_ser_tokens_error<T>(value: &T, tokens: &[Token], error: Error)
     where T: Serialize + PartialEq + Debug
 {
@@ -32,6 +34,7 @@ pub fn assert_ser_tokens_error<T>(value: &T, tokens: &[Token], error: Error)
     assert_eq!(ser.next_token(), None);
 }
 
+/// Asserts that the given `tokens` deserialize into `value`.
 pub fn assert_de_tokens<T>(value: &T, tokens: &[Token<'static>])
     where T: Deserialize + PartialEq + Debug
 {
@@ -41,7 +44,7 @@ pub fn assert_de_tokens<T>(value: &T, tokens: &[Token<'static>])
     assert_eq!(de.next_token(), None);
 }
 
-/// Expect an error deserializing tokens into a `T`.
+/// Asserts that the given `tokens` yield `error` when deserializing.
 pub fn assert_de_tokens_error<T>(tokens: &[Token<'static>], error: Error)
     where T: Deserialize + PartialEq + Debug
 {

serde_test/src/de.rs

@@ -7,6 +7,7 @@ use serde::de::value::{ValueDeserializer, MapVisitorDeserializer, SeqVisitorDese
 use error::Error;
 use token::Token;
 
+/// A `Deserializer` that reads from a list of tokens.
 pub struct Deserializer<I>
     where I: Iterator<Item = Token<'static>>
 {
@@ -16,14 +17,17 @@ pub struct Deserializer<I>
 impl<I> Deserializer<I>
     where I: Iterator<Item = Token<'static>>
 {
+    /// Creates the deserializer.
     pub fn new(tokens: I) -> Deserializer<I> {
         Deserializer { tokens: tokens.peekable() }
     }
 
+    /// Pulls the next token off of the deserializer, ignoring it.
     pub fn next_token(&mut self) -> Option<Token<'static>> {
         self.tokens.next()
     }
 
+    /// Pulls the next token off of the deserializer and checks if it matches an expected token.
     pub fn expect_token(&mut self, expected: Token) -> Result<(), Error> {
         match self.tokens.next() {
             Some(token) => {

serde_test/src/error.rs

@@ -5,11 +5,19 @@ use serde::{ser, de};
 
 use token::Token;
 
+/// Error returned by the test `Serializer` and `Deserializer`.
 #[derive(Clone, PartialEq, Debug)]
 pub enum Error {
+    /// A custom error.
     Message(String),
+
+    /// `Deserialize` was expecting a struct of one name, and another was found.
     InvalidName(&'static str),
+
+    /// `Serialize` generated a token that didn't match the test.
     UnexpectedToken(Token<'static>),
+
+    /// The expected token list was too short.
     EndOfTokens,
 }
 

serde_test/src/ser.rs

@@ -5,6 +5,7 @@ use serde::{ser, Serialize};
 use error::Error;
 use token::Token;
 
+/// A `Serializer` that ensures that a value serializes to a given list of tokens.
 pub struct Serializer<'a, I>
     where I: Iterator<Item = &'a Token<'a>>
 {
@@ -15,6 +16,7 @@ pub struct Serializer<'a, I>
 impl<'a, I> Serializer<'a, I>
     where I: Iterator<Item = &'a Token<'a>>
 {
+    /// Creates the serializer.
     pub fn new(tokens: I) -> Serializer<'a, I> {
         Serializer {
             tokens: tokens,
@@ -22,6 +24,7 @@ impl<'a, I> Serializer<'a, I>
         }
     }
 
+    /// Pulls the next token off of the serializer, ignoring it.
     pub fn next_token(&mut self) -> Option<&'a Token<'a>> {
         self.tokens.next()
     }

serde_test/src/token.rs

@@ -1,59 +1,170 @@
 #[derive(Clone, PartialEq, Debug)]
 pub enum Token<'a> {
+    /// A serialized `bool`.
     Bool(bool),
+
+    /// A serialized `i8`.
     I8(i8),
+
+    /// A serialized `i16`.
     I16(i16),
+
+    /// A serialized `i32`.
     I32(i32),
+
+    /// A serialized `i64`.
     I64(i64),
+
+    /// A serialized `u8`.
     U8(u8),
+
+    /// A serialized `u16`.
     U16(u16),
+
+    /// A serialized `u32`.
     U32(u32),
+
+    /// A serialized `u64`.
     U64(u64),
+
+    /// A serialized `f32`.
     F32(f32),
+
+    /// A serialized `f64`.
     F64(f64),
+
+    /// A serialized `char`.
     Char(char),
+
+    /// A serialized `str`.
     Str(&'a str),
+
+    /// A serialized `String`.
     String(String),
+
+    /// A serialized `[u8]`
     Bytes(&'a [u8]),
+
+    /// A serialized `ByteBuf`
     ByteBuf(Vec<u8>),
 
+    /// The header to a serialized `Option<T>`.
+    ///
+    /// `None` is serialized as `Option(false)`, while `Some` is serialized as `Option(true)`, then
+    /// the value contained in the option.
     Option(bool),
 
+    /// A serialized `()`.
     Unit,
+
+    /// A serialized unit struct of the given name.
     UnitStruct(&'a str),
 
+    /// The header to a serialized newtype struct of the given name.
+    ///
+    /// Newtype structs are serialized with this header, followed by the value contained in the
+    /// newtype struct.
     StructNewType(&'a str),
 
+    /// The header to an enum of the given name.
+    ///
+    /// This token is only used for deserializers, and ensures that the following tokens are read as
+    /// an enum. Because this is never emitted by serializers, calling `assert_ser_tokens` or
+    /// `assert_tokens` will fail if this token is used.
+    ///
+    /// TODO: Trash this.
     EnumStart(&'a str),
+
+    /// A unit variant of an enum of the given name, of the given name.
+    ///
+    /// The first string represents the name of the enum, and the second represents the name of the
+    /// variant.
     EnumUnit(&'a str, &'a str),
+
+    /// The header to a newtype variant of an enum of the given name, of the given name.
+    ///
+    /// The first string represents the name of the enum, and the second represents the name of the
+    /// variant. The value contained within this enum works the same as `StructNewType`.
     EnumNewType(&'a str, &'a str),
 
+    /// The header to a sequence of the given length.
+    ///
+    /// These are serialized via `serialize_seq`, which takes an optional length. After this
+    /// header is a list of elements, followed by `SeqEnd`.
     SeqStart(Option<usize>),
+
+    /// The header to an array of the given length.
+    ///
+    /// These are serialized via `serialize_seq_fized_size`, which requires a length. After this
+    /// header is a list of elements, followed by `SeqEnd`.
     SeqArrayStart(usize),
+
+    /// A separator, which occurs *before* every element in a sequence.
+    ///
+    /// Elements in sequences are represented by a `SeqSep`, followed by the value of the element.
     SeqSep,
+
+    /// An indicator of the end of a sequence.
     SeqEnd,
 
+    /// The header to a tuple of the given length, similar to `SeqArrayStart`.
     TupleStart(usize),
+
+    /// A separator, similar to `SeqSep`.
     TupleSep,
+
+    /// An indicator of the end of a tuple, similar to `SeqEnd`.
     TupleEnd,
 
+    /// The header to a tuple struct of the given name and length.
     TupleStructStart(&'a str, usize),
+
+    /// A separator, similar to `TupleSep`.
     TupleStructSep,
+
+    /// An indicator of the end of a tuple struct, similar to `TupleEnd`.
     TupleStructEnd,
 
+    /// The header to a map of the given length.
+    ///
+    /// These are serialized via `serialize_map`, which takes an optional length. After this header
+    /// is a list of key-value pairs, followed by `MapEnd`.
     MapStart(Option<usize>),
+
+    /// A separator, which occurs *before* every key-value pair in a map.
+    ///
+    /// Elements in maps are represented by a `MapSep`, followed by a serialized key, followed
+    /// by a serialized value.
     MapSep,
+
+    /// An indicator of the end of a map.
     MapEnd,
 
+    /// The header of a struct of the given name and length, similar to `MapStart`.
     StructStart(&'a str, usize),
+
+    /// A separator, similar to `MapSep`.
     StructSep,
+
+    /// An indicator of the end of a struct, similar to `MapEnd`.
     StructEnd,
 
+    /// The header to a tuple variant of an enum of the given name, of the given name and length.
     EnumSeqStart(&'a str, &'a str, usize),
+
+    /// A separator, similar to `TupleSep`.
     EnumSeqSep,
+
+    /// An indicator of the end of a tuple variant, similar to `TupleEnd`.
     EnumSeqEnd,
 
+    /// The header of a struct variant of an enum of the given name, of the given name and length,
+    /// similar to `StructStart`.
     EnumMapStart(&'a str, &'a str, usize),
+
+    /// A separator, similar to `StructSep`.
     EnumMapSep,
+
+    /// An indicator of the end of a struct, similar to `StructEnd`.
     EnumMapEnd,
 }