diff --git a/serde/src/de/mod.rs b/serde/src/de/mod.rs
index af45dbb3..5f9895d5 100644
--- a/serde/src/de/mod.rs
+++ b/serde/src/de/mod.rs
@@ -1799,9 +1799,36 @@ pub trait VariantAccess<'de>: Sized {
 
 ////////////////////////////////////////////////////////////////////////////////
 
-/// This trait converts primitive types into a deserializer.
+/// Converts an existing value into a `Deserializer` from which other values can
+/// be deserialized.
+///
+/// ```rust
+/// #[macro_use]
+/// extern crate serde_derive;
+///
+/// extern crate serde;
+///
+/// use std::str::FromStr;
+/// use serde::de::{value, Deserialize, IntoDeserializer};
+///
+/// #[derive(Deserialize)]
+/// enum Setting {
+///     On,
+///     Off,
+/// }
+///
+/// impl FromStr for Setting {
+///     type Err = value::Error;
+///
+///     fn from_str(s: &str) -> Result<Self, Self::Err> {
+///         Self::deserialize(s.into_deserializer())
+///     }
+/// }
+/// #
+/// # fn main() {}
+/// ```
 pub trait IntoDeserializer<'de, E: Error = value::Error> {
-    /// The actual deserializer type.
+    /// The type of the deserializer being converted into.
     type Deserializer: Deserializer<'de, Error = E>;
 
     /// Convert this value into a deserializer.
diff --git a/serde/src/de/value.rs b/serde/src/de/value.rs
index 921a4ac5..16603b9f 100644
--- a/serde/src/de/value.rs
+++ b/serde/src/de/value.rs
@@ -6,7 +6,34 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! This module supports deserializing from primitives with the `ValueDeserializer` trait.
+//! Building blocks for deserializing basic values using the `IntoDeserializer`
+//! trait.
+//!
+//! ```rust
+//! #[macro_use]
+//! extern crate serde_derive;
+//!
+//! extern crate serde;
+//!
+//! use std::str::FromStr;
+//! use serde::de::{value, Deserialize, IntoDeserializer};
+//!
+//! #[derive(Deserialize)]
+//! enum Setting {
+//!     On,
+//!     Off,
+//! }
+//!
+//! impl FromStr for Setting {
+//!     type Err = value::Error;
+//!
+//!     fn from_str(s: &str) -> Result<Self, Self::Err> {
+//!         Self::deserialize(s.into_deserializer())
+//!     }
+//! }
+//! #
+//! # fn main() {}
+//! ```
 
 use lib::*;
 
@@ -16,7 +43,8 @@ use self::private::{First, Second};
 
 ////////////////////////////////////////////////////////////////////////////////
 
-/// This represents all the possible errors that can occur using the `ValueDeserializer`.
+/// A minimal representation of all possible errors that can occur using the
+/// `IntoDeserializer` trait.
 #[derive(Clone, Debug, PartialEq)]
 pub struct Error {
     err: ErrorImpl,