From 6ccbcdfbc0bf4efc2964246b10a26164be159b6a Mon Sep 17 00:00:00 2001
From: Sean Leather <sean.leather@gmail.com>
Date: Thu, 9 Jul 2020 18:11:45 +0200
Subject: [PATCH] docs: Clarify what BytesMut is (#375)

---
 src/bytes_mut.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/bytes_mut.rs b/src/bytes_mut.rs
index e3fa48f..a7a8e57 100644
--- a/src/bytes_mut.rs
+++ b/src/bytes_mut.rs
@@ -22,8 +22,12 @@ use crate::{Buf, BufMut, 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. It is similar to a `Vec<u8>` but with less copies and
-/// allocations.
+/// mutate the memory.
+///
+/// `BytesMut` can be thought of as containing a `buf: Arc<Vec<u8>>`, an offset
+/// into `buf`, a slice length, and a guarantee that no other `BytesMut` for the
+/// same `buf` overlaps with its slice. That guarantee means that a write lock
+/// is not required.
 ///
 /// # Growth
 ///