docs: comments on interfaces

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]

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{}

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

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

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]