diff --git a/broker.go b/broker.go
index 6d67e05..e404fac 100644
--- a/broker.go
+++ b/broker.go
@@ -10,6 +10,12 @@ import (
 	"github.com/antoniomika/syncmap"
 )
 
+/*
+Broker receives published messages and dispatches the message to the
+subscribing clients. An message contains a message topic that clients
+subscribe to and brokers use these subscription lists for determining the
+clients to receive the message.
+*/
 type Broker interface {
 	GetChannels() iter.Seq2[string, *Channel]
 	GetClients() iter.Seq2[string, *Client]
diff --git a/channel.go b/channel.go
index 257177d..e8f4c3b 100644
--- a/channel.go
+++ b/channel.go
@@ -46,6 +46,10 @@ func NewChannel(topic string) *Channel {
 	}
 }
 
+/*
+Channel is a container for a topic.  It holds the list of clients and
+a data channel to receive a message.
+*/
 type Channel struct {
 	Topic       string
 	Done        chan struct{}
diff --git a/client.go b/client.go
index aada70d..c980532 100644
--- a/client.go
+++ b/client.go
@@ -22,6 +22,11 @@ func NewClient(ID string, rw io.ReadWriter, direction ChannelDirection, blockWri
 	}
 }
 
+/*
+Client is the container for holding state between multiple devices.  A
+client has a direction (input, output, inputout) as well as a way to
+send data to all the associated channels.
+*/
 type Client struct {
 	ID         string
 	ReadWriter io.ReadWriter
diff --git a/multicast.go b/multicast.go
index 38f1cd2..b1237ca 100644
--- a/multicast.go
+++ b/multicast.go
@@ -10,6 +10,17 @@ import (
 	"github.com/antoniomika/syncmap"
 )
 
+/*
+Multicast is a flexible, bidirectional broker.
+
+It provides the most pure version of our PubSub interface which lets
+end-developers build one-to-many connections between publishers and
+subscribers and vice versa.
+
+It doesn't provide any topic filtering capabilities and is only
+concerned with sending data to and from an `io.ReadWriter` via our
+channels.
+*/
 type Multicast struct {
 	Broker
 	Logger *slog.Logger
diff --git a/pubsub.go b/pubsub.go
index 2a6c645..c099619 100644
--- a/pubsub.go
+++ b/pubsub.go
@@ -6,6 +6,13 @@ import (
 	"iter"
 )
 
+/*
+PubSub is our take on a basic publisher and subscriber interface.
+
+It has a few notable requirements:
+- each operation must accept an array of channels
+- some way to send, receive, and stream data between clients
+*/
 type PubSub interface {
 	Broker
 	GetPubs() iter.Seq2[string, *Client]