diff --git a/src/buf/mod.rs b/src/buf/mod.rs
index ceef9270b588ae68afb2504c31c1d17e3c5c3d22..75738c9954a9a120fb867b4b79553eb667b74e74 100644
--- a/src/buf/mod.rs
+++ b/src/buf/mod.rs
@@ -1,3 +1,21 @@
+//! Utilities for working with buffers.
+//!
+//! A buffer is any structure that contains a sequence of bytes. The bytes may
+//! or may not be stored in contiguous memory. This module contains traits used
+//! to abstract over buffers as well as utilities for working with buffer types.
+//!
+//! # `Buf`, `BufMut`
+//!
+//! These are the two foundational traits for abstractly working with buffers.
+//! They can be thought as iterators for byte structures. They offer additional
+//! performance over `Iterator` by providing an API optimized for byte slices.
+//!
+//! See [`Buf`] and [`BufMut`] for more details.
+//!
+//! [rope]: https://en.wikipedia.org/wiki/Rope_(data_structure)
+//! [`Buf`]: trait.Buf.html
+//! [`BufMut`]: trait.BufMut.html
+
 use std::{cmp, io, usize};
 
 mod buf;
diff --git a/src/lib.rs b/src/lib.rs
index 8ac73f4f91fdc8668d4d7bdbf3174c4a71cb97e1..521f80c560ca2418bdbe4d7dbee44be28bce09a9 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -73,17 +73,22 @@
 
 extern crate byteorder;
 
-mod buf;
-mod bytes;
-
+pub mod buf;
 pub use buf::{
     Buf,
     BufMut,
     IntoBuf,
+};
+#[deprecated(since = "0.4.1", note = "moved to `buf` module")]
+#[doc(hidden)]
+pub use buf::{
     Source,
     Reader,
     Writer,
     Take,
 };
+
+mod bytes;
 pub use bytes::{Bytes, BytesMut};
+
 pub use byteorder::{ByteOrder, BigEndian, LittleEndian};