Update docs to highlight differences between DefaultOptions and functions (#373)

Due to historical reasons, the default options used by bincode for the
helper functions at the root of the crate differ from the options in
the `config` module.

Changing the default options is a breaking change, so until a decision
is made, we can at least document the current behavior.

src/config/mod.rs

@@ -1,3 +1,32 @@
+//! `bincode` uses a Builder-pattern to configure the Serializers and Deserializers in this
+//! crate. This means that if you need to customize the behavior of `bincode`, you should create an
+//! instance of the `DefaultOptions` struct:
+//!
+//! ```rust
+//! use bincode::Options;
+//! let my_options = bincode::DefaultOptions::new();
+//! ```
+//!
+//! # Options Struct vs bincode functions
+//!
+//! Due to historical reasons, the default options used by the `serialize()` and `deserialize()`
+//! family of functions are different than the default options created by the `DefaultOptions` struct:
+//!
+//! |          | Byte limit | Endianness | Int Encoding | Trailing Behavior |
+//! |----------|------------|------------|--------------|-------------------|
+//! | struct   | Unlimited  | Little     | Varint       | Reject            |
+//! | function | Unlimited  | Little     | Fixint       | Allow             |
+//!
+//! This means that if you want to use the `Serialize` / `Deserialize` structs with the same
+//! settings as the functions, you should adjust the `DefaultOptions` struct like so:
+//!
+//! ```rust
+//! use bincode::Options;
+//! let my_options = bincode::DefaultOptions::new()
+//!     .with_fixint_encoding()
+//!     .allow_trailing_bytes();
+//! ```
+
 use de::read::BincodeRead;
 use error::Result;
 use serde;
@@ -27,6 +56,23 @@ mod trailing;
 /// ### Defaults
 /// By default bincode will use little-endian encoding for multi-byte integers, and will not
 /// limit the number of serialized/deserialized bytes.
+///
+/// ### Configuring `DefaultOptions`
+///
+/// `DefaultOptions` implements the [Options] trait, which means it exposes functions to change the behavior of bincode.
+///
+/// For example, if you wanted to limit the bincode deserializer to 1 kilobyte of user input:
+///
+/// ```rust
+/// use bincode::Options;
+/// let my_options = bincode::DefaultOptions::new().with_limit(1024);
+/// ```
+///
+/// ### DefaultOptions struct vs. functions
+///
+/// The default configuration used by this struct is not the same as that used by the bincode
+/// helper functions in the root of this crate. See the
+/// [config](index.html#options-struct-vs-bincode-functions) module for more details
 #[derive(Copy, Clone)]
 pub struct DefaultOptions(Infinite);
 

src/lib.rs

@@ -33,7 +33,6 @@ extern crate byteorder;
 #[macro_use]
 extern crate serde;
 
-/// Configuration settings for bincode.
 pub mod config;
 /// Deserialize bincode data to a Rust data structure.
 pub mod de;
@@ -63,6 +62,12 @@ pub fn config() -> Config {
 
 /// Get a default configuration object.
 ///
+/// **Warning:** the default configuration returned by this function
+/// is not the same as that used by the other functions in this
+/// module. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
+/// 
 /// ### Default Configuration:
 ///
 /// | Byte limit | Endianness | Int Encoding | Trailing Behavior |
@@ -77,6 +82,11 @@ pub fn options() -> DefaultOptions {
 ///
 /// If the serialization would take more bytes than allowed by the size limit, an error
 /// is returned and *no bytes* will be written into the `Writer`.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn serialize_into<W, T: ?Sized>(writer: W, value: &T) -> Result<()>
 where
     W: std::io::Write,
@@ -88,6 +98,11 @@ where
 }
 
 /// Serializes a serializable object into a `Vec` of bytes using the default configuration.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn serialize<T: ?Sized>(value: &T) -> Result<Vec<u8>>
 where
     T: serde::Serialize,
@@ -101,6 +116,11 @@ where
 /// Deserializes an object directly from a `Read`er using the default configuration.
 ///
 /// If this returns an `Error`, `reader` may be in an invalid state.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn deserialize_from<R, T>(reader: R) -> Result<T>
 where
     R: std::io::Read,
@@ -117,6 +137,11 @@ where
 /// `BincodeRead` for performance reasons.
 ///
 /// If this returns an `Error`, `reader` may be in an invalid state.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn deserialize_from_custom<'a, R, T>(reader: R) -> Result<T>
 where
     R: de::read::BincodeRead<'a>,
@@ -144,6 +169,11 @@ where
 }
 
 /// Deserializes a slice of bytes into an instance of `T` using the default configuration.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn deserialize<'a, T>(bytes: &'a [u8]) -> Result<T>
 where
     T: serde::de::Deserialize<'a>,
@@ -155,6 +185,11 @@ where
 }
 
 /// Returns the size that an object would be if serialized using Bincode with the default configuration.
+///
+/// **Warning:** the default configuration used by this function is not
+/// the same as that used by the `DefaultOptions` struct. See the
+/// [config](config/index.html#options-struct-vs-bincode-functions)
+/// module for more details
 pub fn serialized_size<T: ?Sized>(value: &T) -> Result<u64>
 where
     T: serde::Serialize,