From c6fa2358e528a1e8aae1aee2f6fd94ef09118b98 Mon Sep 17 00:00:00 2001 From: Ty Overby Date: Mon, 20 Mar 2017 17:32:55 -0700 Subject: [PATCH] add docs to everything that was undocumented --- src/lib.rs | 24 +++++++++++----- src/serde/mod.rs | 12 ++++++-- src/serde/reader.rs | 8 ++++-- src/serde/writer.rs | 68 ++++++++++++++++++++++++--------------------- 4 files changed, 68 insertions(+), 44 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 5515581..92abe36 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,5 @@ +#![deny(missing_docs)] + //! `bincode` is a crate for encoding and decoding using a tiny binary //! serialization strategy. //! @@ -7,11 +9,11 @@ //! and decoding from a `std::io::Buffer`. //! //! ## Modules -//! There are two ways to encode and decode structs using `bincode`, either using `rustc_serialize` -//! or the `serde` crate. `rustc_serialize` and `serde` are crates and and also the names of their -//! corresponding modules inside of `bincode`. Both modules have exactly equivalant functions, and -//! and the only difference is whether or not the library user wants to use `rustc_serialize` or -//! `serde`. +//! Until "default type parameters" lands, we have an extra module called `endian_choice` +//! that duplicates all of the core bincode functionality but with the option to choose +//! which endianness the integers are encoded using. +//! +//! The default endianness is little. //! //! ### Using Basic Functions //! @@ -34,14 +36,13 @@ #![crate_type = "rlib"] #![crate_type = "dylib"] -#![doc(html_logo_url = "./icon.png")] - extern crate byteorder; extern crate num_traits; extern crate serde as serde_crate; mod serde; +/// All of the core bincode functions and types with the ability to choose endianness. pub mod endian_choice { pub use super::serde::{Deserializer, Serializer, serialize, serialize_into, deserialize, deserialize_from}; } @@ -50,7 +51,9 @@ use std::io::{Read, Write}; pub use serde::{ErrorKind, Error, Result, serialized_size, serialized_size_bounded}; +/// A Deserializer that uses LittleEndian byteorder pub type Deserializer = serde::Deserializer; +/// A Serializer that uses LittleEndian byteorder pub type Serializer = serde::Serializer; /// Deserializes a slice of bytes into an object. @@ -121,13 +124,20 @@ pub fn serialize(value: &T, size_limit: S) -> serde::Result Result<()>; + /// Returns the hard limit (if one exists) fn limit(&self) -> Option; } +/// A SizeLimit that restricts serialized or deserialized messages from +/// exceeding a certain byte length. #[derive(Copy, Clone)] pub struct Bounded(pub u64); +/// A SizeLimit without a limit! +/// Use this if you don't care about the size of encoded or decoded messages. #[derive(Copy, Clone)] pub struct Infinite; diff --git a/src/serde/mod.rs b/src/serde/mod.rs index f5c801a..4230bad 100644 --- a/src/serde/mod.rs +++ b/src/serde/mod.rs @@ -23,6 +23,7 @@ use serde_crate as serde; mod reader; mod writer; +/// The result of a serialization or deserialization operation. pub type Result = result::Result; /// An error that can be produced during (de)serializing. @@ -31,6 +32,7 @@ pub type Result = result::Result; /// in an invalid state. pub type Error = Box; +/// The kind of error that can be produced during a serialization or deserialization. #[derive(Debug)] pub enum ErrorKind { /// If the error stems from the reader/writer that is being used @@ -40,14 +42,18 @@ pub enum ErrorKind { /// encoding, this error will be returned. This error is only possible /// if a stream is corrupted. A stream produced from `encode` or `encode_into` /// should **never** produce an InvalidEncoding error. - InvalidEncoding{ - desc: &'static str, + InvalidEncoding { + #[allow(missing_docs)] + desc: &'static str, + #[allow(missing_docs)] detail: Option }, /// If (de)serializing a message takes more than the provided size limit, this /// error is returned. SizeLimit, + /// Bincode can not encode sequences of unknown length (like iterators). SequenceMustHaveLength, + /// A custom error message from Serde. Custom(String) } @@ -194,7 +200,7 @@ pub fn serialized_size(value: &T) -> u64 /// /// If it can be serialized in `max` or fewer bytes, that number will be returned /// inside `Some`. If it goes over bounds, then None is returned. -pub fn serialized_size_bounded(value: &T, max: u64) -> Option +pub fn serialized_size_bounded(value: &T, max: u64) -> Option where T: serde::Serialize { let mut size_counter = SizeChecker { diff --git a/src/serde/reader.rs b/src/serde/reader.rs index 9f5e3af..9093e54 100644 --- a/src/serde/reader.rs +++ b/src/serde/reader.rs @@ -16,6 +16,9 @@ const BLOCK_SIZE: usize = 65536; /// This struct should rarely be used. /// In most cases, prefer the `decode_from` function. /// +/// The ByteOrder that is chosen will impact the endianness that +/// is used to read integers out of the reader. +/// /// ```rust,ignore /// let d = Deserializer::new(&mut some_reader, SizeLimit::new()); /// serde::Deserialize::deserialize(&mut deserializer); @@ -29,6 +32,7 @@ pub struct Deserializer { } impl Deserializer { + /// Creates a new Deserializer with a given `Read`er and a size_limit. pub fn new(r: R, size_limit: S) -> Deserializer { Deserializer { reader: r, @@ -227,7 +231,7 @@ where R: Read, S: SizeLimit, E: ByteOrder { visitor.visit_enum(self) } - + fn deserialize_tuple(self, _len: usize, visitor: V) -> Result where V: serde::de::Visitor, { @@ -330,7 +334,7 @@ where R: Read, S: SizeLimit, E: ByteOrder { let value = try!(serde::de::DeserializeSeed::deserialize(seed, &mut *self.deserializer)); Ok(value) } - + fn size_hint(&self) -> (usize, Option) { (self.len, Some(self.len)) } diff --git a/src/serde/writer.rs b/src/serde/writer.rs index 203b677..2d6b7a0 100644 --- a/src/serde/writer.rs +++ b/src/serde/writer.rs @@ -11,6 +11,9 @@ use super::super::SizeLimit; /// An Serializer that encodes values directly into a Writer. /// +/// The specified byte-order will impact the endianness that is +/// used during the encoding. +/// /// This struct should not be used often. /// For most cases, prefer the `encode_into` function. pub struct Serializer { @@ -19,6 +22,7 @@ pub struct Serializer { } impl Serializer { + /// Creates a new Serializer with the given `Write`r. pub fn new(w: W) -> Serializer { Serializer { writer: w, @@ -392,8 +396,8 @@ impl<'a, W, E> serde::ser::SerializeSeq for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_element(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_element(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -411,8 +415,8 @@ impl<'a, W, E> serde::ser::SerializeTuple for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_element(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_element(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -430,8 +434,8 @@ impl<'a, W, E> serde::ser::SerializeTupleStruct for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_field(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -449,8 +453,8 @@ impl<'a, W, E> serde::ser::SerializeTupleVariant for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_field(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -468,15 +472,15 @@ impl<'a, W, E> serde::ser::SerializeMap for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_key(&mut self, value: &K) -> Result<()> - where K: serde::ser::Serialize + fn serialize_key(&mut self, value: &K) -> Result<()> + where K: serde::ser::Serialize { value.serialize(&mut *self.ser) } #[inline] - fn serialize_value(&mut self, value: &V) -> Result<()> - where V: serde::ser::Serialize + fn serialize_value(&mut self, value: &V) -> Result<()> + where V: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -494,8 +498,8 @@ impl<'a, W, E> serde::ser::SerializeStruct for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -513,8 +517,8 @@ impl<'a, W, E> serde::ser::SerializeStructVariant for Compound<'a, W, E> type Error = Error; #[inline] - fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -536,8 +540,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeSeq for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_element(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_element(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -554,8 +558,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTuple for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_element(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_element(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -572,8 +576,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleStruct for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_field(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -590,8 +594,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeTupleVariant for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_field(&mut self, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -608,15 +612,15 @@ impl<'a, S: SizeLimit + 'a> serde::ser::SerializeMap for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_key(&mut self, value: &K) -> Result<()> - where K: serde::ser::Serialize + fn serialize_key(&mut self, value: &K) -> Result<()> + where K: serde::ser::Serialize { value.serialize(&mut *self.ser) } #[inline] - fn serialize_value(&mut self, value: &V) -> Result<()> - where V: serde::ser::Serialize + fn serialize_value(&mut self, value: &V) -> Result<()> + where V: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -633,8 +637,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStruct for SizeCompound<'a, S> type Error = Error; #[inline] - fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) } @@ -651,8 +655,8 @@ impl<'a, S: SizeLimit> serde::ser::SerializeStructVariant for SizeCompound<'a, S type Error = Error; #[inline] - fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> - where T: serde::ser::Serialize + fn serialize_field(&mut self, _key: &'static str, value: &T) -> Result<()> + where T: serde::ser::Serialize { value.serialize(&mut *self.ser) }