diff --git a/mcache.go b/mcache.go
index 827987a..9f5e5dc 100644
--- a/mcache.go
+++ b/mcache.go
@@ -1,10 +1,29 @@
 package pubsub
 
 import (
+	"fmt"
+
 	pb "github.com/libp2p/go-libp2p-pubsub/pb"
 )
 
+// NewMessageCache creates a sliding window cache that remembers messages for as
+// long as `history` slots.
+//
+// When queried for messages to advertise, the cache only returns messages in
+// the last `gossip` slots.
+//
+// The `gossip` parameter must be smaller or equal to `history`, or this
+// function will panic.
+//
+// The slack between `gossip` and `history` accounts for the reaction time
+// between when a message is advertised via IHAVE gossip, and the peer pulls it
+// via an IWANT command.
 func NewMessageCache(gossip, history int) *MessageCache {
+	if gossip > history {
+		err := fmt.Errorf("invalid parameters for message cache; gossip slots (%d) cannot be larger than history slots (%d)",
+			gossip, history)
+		panic(err)
+	}
 	return &MessageCache{
 		msgs:    make(map[string]*pb.Message),
 		history: make([][]CacheEntry, history),