From a40f23ad4a851d20abb6d339db3b82b8c6567a26 Mon Sep 17 00:00:00 2001
From: Brad Fitzpatrick <bradfitz@tailscale.com>
Date: Thu, 25 Sep 2025 09:39:27 -0700
Subject: [PATCH] util/eventbus: flesh out docs a bit

Updates #cleanup

Change-Id: Ia6b0e4b0426be1dd10a777aff0a81d4dd6b69b01
Signed-off-by: Brad Fitzpatrick <bradfitz@tailscale.com>
---
 util/eventbus/bus.go       | 2 +-
 util/eventbus/client.go    | 2 +-
 util/eventbus/publish.go   | 4 ++++
 util/eventbus/subscribe.go | 6 +++++-
 4 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/util/eventbus/bus.go b/util/eventbus/bus.go
index e5bf7329a..d1507d8e6 100644
--- a/util/eventbus/bus.go
+++ b/util/eventbus/bus.go
@@ -77,7 +77,7 @@ func (b *Bus) Debugger() *Debugger {
 	return &Debugger{b}
 }
 
-// Close closes the bus. Implicitly closes all clients, publishers and
+// Close closes the bus. It implicitly closes all clients, publishers and
 // subscribers attached to the bus.
 //
 // Close blocks until the bus is fully shut down. The bus is
diff --git a/util/eventbus/client.go b/util/eventbus/client.go
index 9b4119865..7c0268886 100644
--- a/util/eventbus/client.go
+++ b/util/eventbus/client.go
@@ -29,7 +29,7 @@ type Client struct {
 
 func (c *Client) Name() string { return c.name }
 
-// Close closes the client. Implicitly closes all publishers and
+// Close closes the client. It implicitly closes all publishers and
 // subscribers obtained from this client.
 func (c *Client) Close() {
 	var (
diff --git a/util/eventbus/publish.go b/util/eventbus/publish.go
index 4a4bdfb7e..348bb9dff 100644
--- a/util/eventbus/publish.go
+++ b/util/eventbus/publish.go
@@ -27,6 +27,10 @@ func newPublisher[T any](c *Client) *Publisher[T] {
 // Close closes the publisher.
 //
 // Calls to Publish after Close silently do nothing.
+//
+// If the Bus or Client from which the Publisher was created is closed,
+// the Publisher is implicitly closed and does not need to be closed
+// separately.
 func (p *Publisher[T]) Close() {
 	// Just unblocks any active calls to Publish, no other
 	// synchronization needed.
diff --git a/util/eventbus/subscribe.go b/util/eventbus/subscribe.go
index ee534781a..ef155e621 100644
--- a/util/eventbus/subscribe.go
+++ b/util/eventbus/subscribe.go
@@ -158,7 +158,7 @@ func (q *subscribeState) subscriberFor(val any) subscriber {
 	return q.outputs[reflect.TypeOf(val)]
 }
 
-// Close closes the subscribeState. Implicitly closes all Subscribers
+// Close closes the subscribeState. It implicitly closes all Subscribers
 // linked to this state, and any pending events are discarded.
 func (s *subscribeState) close() {
 	s.dispatcher.StopAndWait()
@@ -244,6 +244,10 @@ func (s *Subscriber[T]) Done() <-chan struct{} {
 // Close closes the Subscriber, indicating the caller no longer wishes
 // to receive this event type. After Close, receives on
 // [Subscriber.Events] block for ever.
+//
+// If the Bus from which the Subscriber was created is closed,
+// the Subscriber is implicitly closed and does not need to be closed
+// separately.
 func (s *Subscriber[T]) Close() {
 	s.stop.Stop() // unblock receivers
 	s.unregister()