diff --git a/pkg/mining/metrics.go b/pkg/mining/metrics.go
index 5a62015..c35d626 100644
--- a/pkg/mining/metrics.go
+++ b/pkg/mining/metrics.go
@@ -41,7 +41,7 @@ type LatencyHistogram struct {
 	maxSize int
 }
 
-// NewLatencyHistogram creates a new latency histogram with a maximum sample size.
+// h := mining.NewLatencyHistogram(1000)  // retain up to 1000 latency samples
 func NewLatencyHistogram(maxSize int) *LatencyHistogram {
 	return &LatencyHistogram{
 		samples: make([]time.Duration, 0, maxSize),
@@ -62,7 +62,7 @@ func (h *LatencyHistogram) Record(d time.Duration) {
 	h.samples = append(h.samples, d)
 }
 
-// Average returns the average latency.
+// avg := h.Average()  // returns 0 if no samples recorded
 func (h *LatencyHistogram) Average() time.Duration {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -78,7 +78,7 @@ func (h *LatencyHistogram) Average() time.Duration {
 	return total / time.Duration(len(h.samples))
 }
 
-// Count returns the number of samples.
+// if h.Count() == 0 { return }  // guard before calling Average()
 func (h *LatencyHistogram) Count() int {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -90,7 +90,8 @@ var DefaultMetrics = &Metrics{
 	RequestLatency: NewLatencyHistogram(1000),
 }
 
-// RecordRequest records an API request.
+// RecordRequest(true, 42*time.Millisecond)  // errored request
+// RecordRequest(false, 5*time.Millisecond)  // successful request
 func RecordRequest(errored bool, latency time.Duration) {
 	DefaultMetrics.RequestsTotal.Add(1)
 	if errored {
@@ -99,22 +100,24 @@ func RecordRequest(errored bool, latency time.Duration) {
 	DefaultMetrics.RequestLatency.Record(latency)
 }
 
-// RecordMinerStart records a miner start event.
+// RecordMinerStart()  // call after miner.Start() succeeds
 func RecordMinerStart() {
 	DefaultMetrics.MinersStarted.Add(1)
 }
 
-// RecordMinerStop records a miner stop event.
+// RecordMinerStop()  // call after miner.Stop() completes
 func RecordMinerStop() {
 	DefaultMetrics.MinersStopped.Add(1)
 }
 
-// RecordMinerError records a miner error event.
+// RecordMinerError()  // call when a miner crashes or fails to respond
 func RecordMinerError() {
 	DefaultMetrics.MinersErrored.Add(1)
 }
 
-// RecordStatsCollection records a stats collection event.
+// RecordStatsCollection(false, false)  // successful first-attempt collection
+// RecordStatsCollection(true, false)   // succeeded after retry
+// RecordStatsCollection(true, true)    // failed after retry
 func RecordStatsCollection(retried bool, failed bool) {
 	DefaultMetrics.StatsCollected.Add(1)
 	if retried {
@@ -125,7 +128,8 @@ func RecordStatsCollection(retried bool, failed bool) {
 	}
 }
 
-// RecordWSConnection increments or decrements WebSocket connection count.
+// RecordWSConnection(true)   // client connected
+// RecordWSConnection(false)  // client disconnected
 func RecordWSConnection(connected bool) {
 	if connected {
 		DefaultMetrics.WSConnections.Add(1)
@@ -134,12 +138,13 @@ func RecordWSConnection(connected bool) {
 	}
 }
 
-// RecordWSMessage records a WebSocket message.
+// RecordWSMessage()  // call after broadcasting an event to clients
 func RecordWSMessage() {
 	DefaultMetrics.WSMessages.Add(1)
 }
 
-// RecordP2PMessage records a P2P message.
+// RecordP2PMessage(true)   // outbound message dispatched
+// RecordP2PMessage(false)  // inbound message received
 func RecordP2PMessage(sent bool) {
 	if sent {
 		DefaultMetrics.P2PMessagesSent.Add(1)
@@ -148,7 +153,8 @@ func RecordP2PMessage(sent bool) {
 	}
 }
 
-// GetMetricsSnapshot returns a snapshot of current metrics.
+// snapshot := mining.GetMetricsSnapshot()
+// snapshot["requests_total"].(int64)
 func GetMetricsSnapshot() map[string]interface{} {
 	return map[string]interface{}{
 		"requests_total":          DefaultMetrics.RequestsTotal.Load(),