metrics: fix docstrings (#29279)

Author: georgehao

metrics/json.go

@@ -26,6 +26,6 @@ func WriteJSONOnce(r Registry, w io.Writer) {
 	json.NewEncoder(w).Encode(r)
 }
 
-func (p *PrefixedRegistry) MarshalJSON() ([]byte, error) {
-	return json.Marshal(p.GetAll())
+func (r *PrefixedRegistry) MarshalJSON() ([]byte, error) {
+	return json.Marshal(r.GetAll())
 }

metrics/registry.go

@@ -8,8 +8,8 @@ import (
 	"sync"
 )
 
-// DuplicateMetric is the error returned by Registry.Register when a metric
-// already exists.  If you mean to Register that metric you must first
+// DuplicateMetric is the error returned by Registry. Register when a metric
+// already exists. If you mean to Register that metric you must first
 // Unregister the existing metric.
 type DuplicateMetric string
 
@@ -20,11 +20,11 @@ func (err DuplicateMetric) Error() string {
 // A Registry holds references to a set of metrics by name and can iterate
 // over them, calling callback functions provided by the user.
 //
-// This is an interface so as to encourage other structs to implement
+// This is an interface to encourage other structs to implement
 // the Registry API as appropriate.
 type Registry interface {
 
-	// Call the given function for each registered metric.
+	// Each call the given function for each registered metric.
 	Each(func(string, interface{}))
 
 	// Get the metric by the given name or nil if none is registered.
@@ -33,15 +33,15 @@ type Registry interface {
 	// GetAll metrics in the Registry.
 	GetAll() map[string]map[string]interface{}
 
-	// Gets an existing metric or registers the given one.
+	// GetOrRegister gets an existing metric or registers the given one.
 	// The interface can be the metric to register if not found in registry,
 	// or a function returning the metric for lazy instantiation.
 	GetOrRegister(string, interface{}) interface{}
 
 	// Register the given metric under the given name.
 	Register(string, interface{}) error
 
-	// Run all registered healthchecks.
+	// RunHealthchecks run all registered healthchecks.
 	RunHealthchecks()
 
 	// Unregister the metric with the given name.
@@ -52,7 +52,7 @@ type orderedRegistry struct {
 	StandardRegistry
 }
 
-// Call the given function for each registered metric.
+// Each call the given function for each registered metric.
 func (r *orderedRegistry) Each(f func(string, interface{})) {
 	var names []string
 	reg := r.registered()
@@ -75,13 +75,13 @@ func NewOrderedRegistry() Registry {
 	return new(orderedRegistry)
 }
 
-// The standard implementation of a Registry uses sync.map
+// StandardRegistry the standard implementation of a Registry uses sync.map
 // of names to metrics.
 type StandardRegistry struct {
 	metrics sync.Map
 }
 
-// Call the given function for each registered metric.
+// Each call the given function for each registered metric.
 func (r *StandardRegistry) Each(f func(string, interface{})) {
 	for name, i := range r.registered() {
 		f(name, i)
@@ -94,7 +94,7 @@ func (r *StandardRegistry) Get(name string) interface{} {
 	return item
 }
 
-// Gets an existing metric or creates and registers a new one. Threadsafe
+// GetOrRegister gets an existing metric or creates and registers a new one. Threadsafe
 // alternative to calling Get and Register on failure.
 // The interface can be the metric to register if not found in registry,
 // or a function returning the metric for lazy instantiation.
@@ -114,7 +114,7 @@ func (r *StandardRegistry) GetOrRegister(name string, i interface{}) interface{}
 	return item
 }
 
-// Register the given metric under the given name.  Returns a DuplicateMetric
+// Register the given metric under the given name. Returns a DuplicateMetric
 // if a metric by the given name is already registered.
 func (r *StandardRegistry) Register(name string, i interface{}) error {
 	// fast path
@@ -133,7 +133,7 @@ func (r *StandardRegistry) Register(name string, i interface{}) error {
 	return nil
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks run all registered healthchecks.
 func (r *StandardRegistry) RunHealthchecks() {
 	r.metrics.Range(func(key, value any) bool {
 		if h, ok := value.(Healthcheck); ok {
@@ -263,7 +263,7 @@ func NewPrefixedChildRegistry(parent Registry, prefix string) Registry {
 	}
 }
 
-// Call the given function for each registered metric.
+// Each call the given function for each registered metric.
 func (r *PrefixedRegistry) Each(fn func(string, interface{})) {
 	wrappedFn := func(prefix string) func(string, interface{}) {
 		return func(name string, iface interface{}) {
@@ -295,7 +295,7 @@ func (r *PrefixedRegistry) Get(name string) interface{} {
 	return r.underlying.Get(realName)
 }
 
-// Gets an existing metric or registers the given one.
+// GetOrRegister gets an existing metric or registers the given one.
 // The interface can be the metric to register if not found in registry,
 // or a function returning the metric for lazy instantiation.
 func (r *PrefixedRegistry) GetOrRegister(name string, metric interface{}) interface{} {
@@ -309,7 +309,7 @@ func (r *PrefixedRegistry) Register(name string, metric interface{}) error {
 	return r.underlying.Register(realName, metric)
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks run all registered healthchecks.
 func (r *PrefixedRegistry) RunHealthchecks() {
 	r.underlying.RunHealthchecks()
 }
@@ -331,7 +331,7 @@ var (
 	AccountingRegistry = NewRegistry() // registry used in swarm
 )
 
-// Call the given function for each registered metric.
+// Each call the given function for each registered metric.
 func Each(f func(string, interface{})) {
 	DefaultRegistry.Each(f)
 }
@@ -341,7 +341,7 @@ func Get(name string) interface{} {
 	return DefaultRegistry.Get(name)
 }
 
-// Gets an existing metric or creates and registers a new one. Threadsafe
+// GetOrRegister gets an existing metric or creates and registers a new one. Threadsafe
 // alternative to calling Get and Register on failure.
 func GetOrRegister(name string, i interface{}) interface{} {
 	return DefaultRegistry.GetOrRegister(name, i)
@@ -353,15 +353,15 @@ func Register(name string, i interface{}) error {
 	return DefaultRegistry.Register(name, i)
 }
 
-// Register the given metric under the given name.  Panics if a metric by the
+// MustRegister register the given metric under the given name. Panics if a metric by the
 // given name is already registered.
 func MustRegister(name string, i interface{}) {
 	if err := Register(name, i); err != nil {
 		panic(err)
 	}
 }
 
-// Run all registered healthchecks.
+// RunHealthchecks run all registered healthchecks.
 func RunHealthchecks() {
 	DefaultRegistry.RunHealthchecks()
 }

metrics/timer.go

@@ -10,7 +10,7 @@ type TimerSnapshot interface {
 	MeterSnapshot
 }
 
-// Timers capture the duration and rate of events.
+// Timer capture the duration and rate of events.
 type Timer interface {
 	Snapshot() TimerSnapshot
 	Stop()
@@ -99,22 +99,22 @@ func (t *StandardTimer) Stop() {
 	t.meter.Stop()
 }
 
-// Record the duration of the execution of the given function.
+// Time record the duration of the execution of the given function.
 func (t *StandardTimer) Time(f func()) {
 	ts := time.Now()
 	f()
 	t.Update(time.Since(ts))
 }
 
-// Record the duration of an event, in nanoseconds.
+// Update the duration of an event, in nanoseconds.
 func (t *StandardTimer) Update(d time.Duration) {
 	t.mutex.Lock()
 	defer t.mutex.Unlock()
 	t.histogram.Update(d.Nanoseconds())
 	t.meter.Mark(1)
 }
 
-// Record the duration of an event that started at a time and ends now.
+// UpdateSince update the duration of an event that started at a time and ends now.
 // The record uses nanoseconds.
 func (t *StandardTimer) UpdateSince(ts time.Time) {
 	t.Update(time.Since(ts))