Tweak docs (#76)

src/buf/buf.rs

@@ -9,7 +9,8 @@ use std::{cmp, io, ptr};
 /// A buffer stores bytes in memory such that read operations are infallible.
 /// The underlying storage may or may not be in contiguous memory. A `Buf` value
 /// is a cursor into the buffer. Reading from `Buf` advances the cursor
-/// position.
+/// position. It can be thought of as an efficient `Iterator` for collections of
+/// bytes.
 ///
 /// The simplest `Buf` is a `Cursor` wrapping a `[u8]`.
 ///

src/bytes.rs

@@ -107,10 +107,24 @@ pub struct Bytes {
 ///
 /// `BytesMut` represents a unique view into a potentially shared memory region.
 /// Given the uniqueness guarantee, owners of `BytesMut` handles are able to
-/// mutate the memory.
+/// mutate the memory. It is similar to a `Vec<u8>` but with less copies and
+/// allocations.
 ///
 /// For more detail, see [Bytes](struct.Bytes.html).
 ///
+/// # Growth
+///
+/// One key difference from `Vec<u8>` is that most operations **do not
+/// implicitly grow the buffer**. This means that calling `my_bytes.put("hello
+/// world");` could panic if `my_bytes` does not have enough capacity. Before
+/// writing to the buffer, ensure that there is enough remaining capacity by
+/// calling `my_bytes.remaining_mut()`. In general, avoiding calls to `reserve`
+/// is preferable.
+///
+/// The only exception is `extend` which implicitly reserves required capacity.
+///
+/// # Examples
+///
 /// ```
 /// use bytes::{BytesMut, BufMut};
 ///