1diff --git a/broker.go b/broker.go
2index 6d67e05..e404fac 100644
3--- a/broker.go
4+++ b/broker.go
5@@ -10,6 +10,12 @@ import (
6 "github.com/antoniomika/syncmap"
7 )
8
9+/*
10+Broker receives published messages and dispatches the message to the
11+subscribing clients. An message contains a message topic that clients
12+subscribe to and brokers use these subscription lists for determining the
13+clients to receive the message.
14+*/
15 type Broker interface {
16 GetChannels() iter.Seq2[string, *Channel]
17 GetClients() iter.Seq2[string, *Client]
18diff --git a/channel.go b/channel.go
19index 257177d..e8f4c3b 100644
20--- a/channel.go
21+++ b/channel.go
22@@ -46,6 +46,10 @@ func NewChannel(topic string) *Channel {
23 }
24 }
25
26+/*
27+Channel is a container for a topic. It holds the list of clients and
28+a data channel to receive a message.
29+*/
30 type Channel struct {
31 Topic string
32 Done chan struct{}
33diff --git a/client.go b/client.go
34index aada70d..c980532 100644
35--- a/client.go
36+++ b/client.go
37@@ -22,6 +22,11 @@ func NewClient(ID string, rw io.ReadWriter, direction ChannelDirection, blockWri
38 }
39 }
40
41+/*
42+Client is the container for holding state between multiple devices. A
43+client has a direction (input, output, inputout) as well as a way to
44+send data to all the associated channels.
45+*/
46 type Client struct {
47 ID string
48 ReadWriter io.ReadWriter
49diff --git a/multicast.go b/multicast.go
50index 38f1cd2..b1237ca 100644
51--- a/multicast.go
52+++ b/multicast.go
53@@ -10,6 +10,17 @@ import (
54 "github.com/antoniomika/syncmap"
55 )
56
57+/*
58+Multicast is a flexible, bidirectional broker.
59+
60+It provides the most pure version of our PubSub interface which lets
61+end-developers build one-to-many connections between publishers and
62+subscribers and vice versa.
63+
64+It doesn't provide any topic filtering capabilities and is only
65+concerned with sending data to and from an `io.ReadWriter` via our
66+channels.
67+*/
68 type Multicast struct {
69 Broker
70 Logger *slog.Logger
71diff --git a/pubsub.go b/pubsub.go
72index 2a6c645..c099619 100644
73--- a/pubsub.go
74+++ b/pubsub.go
75@@ -6,6 +6,13 @@ import (
76 "iter"
77 )
78
79+/*
80+PubSub is our take on a basic publisher and subscriber interface.
81+
82+It has a few notable requirements:
83+- each operation must accept an array of channels
84+- some way to send, receive, and stream data between clients
85+*/
86 type PubSub interface {
87 Broker
88 GetPubs() iter.Seq2[string, *Client]