diff --git a/bitswap/client/internal/messagequeue/doc.go b/bitswap/client/internal/messagequeue/doc.go
new file mode 100644
index 000000000..8a48a7b57
--- /dev/null
+++ b/bitswap/client/internal/messagequeue/doc.go
@@ -0,0 +1,29 @@
+// Package messagequeue implements a queue of want messages to send to peers.
+//
+// There is a MessageQueue for each peer. The MessageQueue does not enqueue
+// individual outgoing messages, but accumulates information to put into the
+// next message. Each MessageQueue keeps want lists and CIDs to cancel:
+//
+//   - sent/pending peer wants + sent times
+//   - sent/pending broadcast wants + sent times
+//   - cancel CIDs
+//
+// As messages are added, existing wantlist items may be changed or removed.
+// For example, adding a cancel to the queue for some CIDs also removes any
+// pending wants for those same CIDs. Adding a want will remove a cancel for
+// that CID. If a want already exists then only the type and priority may be
+// adjusted for that same want, so that duplicate messages are not sent.
+//
+// When enough message updates have accumulated or it has been long enough
+// since the previous message was sent, then send the current message. The
+// message contains wants and cancels up to a limited size, and is sent to the
+// peer. The time that the message was sent is recorded.
+//
+// If a want has been sent with no response received, for longer than the
+// rebroadcast interval, then the want is moved back to the pending list to be
+// resent to the peer.
+//
+// When a response is received, the earliest request time is used to calculate
+// the longest latency for updating the message timeout time. The sent times
+// are cleared for CIDs in the response.
+package messagequeue
diff --git a/bitswap/client/internal/messagequeue/messagequeue.go b/bitswap/client/internal/messagequeue/messagequeue.go
index 2f808874d..a8ab99830 100644
--- a/bitswap/client/internal/messagequeue/messagequeue.go
+++ b/bitswap/client/internal/messagequeue/messagequeue.go
@@ -61,27 +61,6 @@ type MessageNetwork interface {
 }
 
 // MessageQueue implements queue of want messages to send to peers.
-//
-// There is a MessageQueue for each peer. Each MessageQueue keeps want lists
-// and CIDs to cancel:
-//
-//   - sent/pending peer wants + sent times
-//   - sent/pending broadcast wants + sent times
-//   - cancel CIDs
-//
-// As different messages are added, existing messages already present may be
-// changed or removed. For example, adding a cancel to the queue for some CIDs
-// will also remove any pending wants for those same CIDs. Adding a want will
-// remove a cancel for that CID. If a want already exists then only the type
-// and priority may be adjusted for that same want, so that duplicate messages
-// are not sent.
-//
-// Periodically, on a schedule determined by the peer's response latency, the
-// current set of messages (wants and cancels) is sent to the peer. The time
-// that wants are sent is recorded. When a response to a want message is
-// received, the elapsed time since the request was sent is recorded in the
-// message queue. If there are a sufficient number of updates to send, a
-// bitswap message is sent immediately.
 type MessageQueue struct {
 	ctx          context.Context
 	shutdown     func()