diff --git a/config.go b/config.go
index a33bb71..681b5bc 100644
--- a/config.go
+++ b/config.go
@@ -1,6 +1,6 @@
 package proxy
 
-// Config is the top-level proxy configuration.
+// Config is the top-level proxy configuration used by `proxy.New`.
 //
 //	cfg := &proxy.Config{
 //	    Mode:    "nicehash",
diff --git a/customdiffstats.go b/customdiffstats.go
index 3b8a05c..e370f6a 100644
--- a/customdiffstats.go
+++ b/customdiffstats.go
@@ -14,7 +14,7 @@ type CustomDiffBucketStats struct {
 	HashesTotal uint64 `json:"hashes_total"`
 }
 
-// CustomDiffBuckets records share totals grouped by miner custom difficulty.
+// CustomDiffBuckets groups share totals by the miner's resolved custom difficulty.
 //
 //	buckets := NewCustomDiffBuckets(true)
 //	buckets.OnAccept(Event{Miner: &Miner{customDiff: 50000}, Diff: 25000})
diff --git a/stats.go b/stats.go
index 3e04406..ac2aa05 100644
--- a/stats.go
+++ b/stats.go
@@ -6,11 +6,11 @@ import (
 	"time"
 )
 
-// Stats tracks the proxy-wide counters and rolling hashrate windows.
+// Stats tracks proxy-wide counters and rolling hashrate windows.
 //
-// stats := proxy.NewStats()
-// bus.Subscribe(proxy.EventAccept, stats.OnAccept)
-// bus.Subscribe(proxy.EventReject, stats.OnReject)
+//	stats := proxy.NewStats()
+//	bus.Subscribe(proxy.EventAccept, stats.OnAccept)
+//	bus.Subscribe(proxy.EventReject, stats.OnReject)
 type Stats struct {
 	accepted    atomic.Uint64
 	rejected    atomic.Uint64
@@ -50,7 +50,7 @@ type tickWindow struct {
 
 // StatsSummary is the serialisable snapshot returned by Stats.Summary().
 //
-// summary := proxy.NewStats().Summary()
+//	summary := proxy.NewStats().Summary()
 type StatsSummary struct {
 	Accepted        uint64                           `json:"accepted"`
 	Rejected        uint64                           `json:"rejected"`
diff --git a/worker.go b/worker.go
index ff6cf7c..a7d9c01 100644
--- a/worker.go
+++ b/worker.go
@@ -5,7 +5,7 @@ import (
 	"time"
 )
 
-// Workers tracks per-identity aggregates derived from miner login fields.
+// Workers tracks per-worker aggregates derived from miner login fields.
 //
 //	workers := proxy.NewWorkers(proxy.WorkersByRigID, bus)
 //	workers.OnLogin(proxy.Event{Miner: &proxy.Miner{rigID: "rig-alpha", user: "WALLET", ip: "10.0.0.1"}})
@@ -18,7 +18,7 @@ type Workers struct {
 	mu         sync.RWMutex
 }
 
-// WorkerRecord is the aggregate row returned by Workers.List().
+// WorkerRecord is the aggregate row returned by `Workers.List()`.
 //
 //	record := proxy.WorkerRecord{Name: "rig-alpha"}
 //	_ = record.Hashrate(60)