diff --git a/pkg/mining/metrics.go b/pkg/mining/metrics.go
index 2476fe6..b6bbac6 100644
--- a/pkg/mining/metrics.go
+++ b/pkg/mining/metrics.go
@@ -6,8 +6,8 @@ import (
 	"time"
 )
 
-// Metrics provides simple instrumentation counters for the mining package.
-// These can be exposed via Prometheus or other metrics systems in the future.
+// snapshot := mining.GetMetricsSnapshot()
+// snapshot["miners_started"].(int64)
 type Metrics struct {
 	// API metrics
 	RequestsTotal   atomic.Int64
@@ -34,7 +34,8 @@ type Metrics struct {
 	P2PConnectionsTotal atomic.Int64
 }
 
-// LatencyHistogram tracks request latencies with basic percentile support.
+// h := mining.NewLatencyHistogram(1000)
+// h.Record(42 * time.Millisecond)
 type LatencyHistogram struct {
 	mu      sync.Mutex
 	samples []time.Duration