From e5c63021508ff6633e4b0ed29eb61bd6a38793de Mon Sep 17 00:00:00 2001 From: beorn7 Date: Wed, 3 Aug 2016 12:23:37 +0200 Subject: [PATCH] Fix a number of doc comments and similar nits --- prometheus/collector.go | 6 +++--- prometheus/counter.go | 6 +++--- prometheus/doc.go | 16 ++++++++-------- prometheus/example_clustermanager_test.go | 6 +++--- prometheus/push/examples_test.go | 4 ++-- prometheus/registry.go | 15 ++++++++------- 6 files changed, 27 insertions(+), 26 deletions(-) diff --git a/prometheus/collector.go b/prometheus/collector.go index d0f2969..623d3d8 100644 --- a/prometheus/collector.go +++ b/prometheus/collector.go @@ -50,9 +50,9 @@ type Collector interface { Collect(chan<- Metric) } -// selfCollector implements Collector for a single Metric so that that the -// Metric collects itself. Add it as an anonymous field to a struct that -// implements Metric, and call Init with the Metric itself as an argument. +// selfCollector implements Collector for a single Metric so that the Metric +// collects itself. Add it as an anonymous field to a struct that implements +// Metric, and call init with the Metric itself as an argument. type selfCollector struct { self Metric } diff --git a/prometheus/counter.go b/prometheus/counter.go index bf44cc8..0537f88 100644 --- a/prometheus/counter.go +++ b/prometheus/counter.go @@ -35,9 +35,9 @@ type Counter interface { // Prometheus metric. Do not use it for regular handling of a // Prometheus counter (as it can be used to break the contract of // monotonically increasing values). - // This method is DEPRECATED. Use NewConstMetric to create a counter for - // an external value. - // TODO(beorn7): Remove. + // + // Deprecated: Use NewConstMetric to create a counter for an external + // value. A Counter should never be set. Set(float64) // Inc increments the counter by 1. Inc() diff --git a/prometheus/doc.go b/prometheus/doc.go index ce93443..08ac233 100644 --- a/prometheus/doc.go +++ b/prometheus/doc.go @@ -71,7 +71,7 @@ // // Above, you have already touched the Counter and the Gauge. There are two more // advanced metric types: the Summary and Histogram. A more thorough description -// of those four metric types can be found in the prometheus docs: +// of those four metric types can be found in the Prometheus docs: // https://prometheus.io/docs/concepts/metric_types/ // // A fifth "type" of metric is Untyped. It behaves like a Gauge, but signals the @@ -83,7 +83,7 @@ // metric vectors. The fundamental types are GaugeVec, CounterVec, SummaryVec, // HistogramVec, and UntypedVec. // -// While only the fudamental metric types implement the Metric interface, both +// While only the fundamental metric types implement the Metric interface, both // the metrics and their vector versions implement the Collector interface. A // Collector manages the collection of a number of Metrics, but for convenience, // a Metric can also “collect itself”. Note that Gauge, Counter, Summary, @@ -102,7 +102,7 @@ // registration (with the prime example of the different metric vectors above, // which bundle all the metrics of the same name but with different labels). // -// There is a more involved use-case, too: If you already have metrics +// There is a more involved use case, too: If you already have metrics // available, created outside of the Prometheus context, you don't need the // interface of the various Metric types. You essentially want to mirror the // existing numbers into Prometheus Metrics during collection. An own @@ -113,9 +113,9 @@ // instances, representative of the “throw-away” metrics to be created // later. NewDesc comes in handy to create those Desc instances. // -// The Collector example illustrates the use-case. You can also look at the +// The Collector example illustrates the use case. You can also look at the // source code of the processCollector (mirroring process metrics), the -// goCollector (mirroring Go metrics), or the exvarCollector (mirroring expvar +// goCollector (mirroring Go metrics), or the expvarCollector (mirroring expvar // metrics) as examples that are used in this package itself. // // If you just need to call a function to get a single float value to collect as @@ -161,9 +161,9 @@ // // The Handler function used so far to get an http.Handler for serving the // metrics is also acting on the DefaultRegistry. With HandlerFor, you can -// create a handler for a custom registry or anything the implements the -// Deliverer interface. It also allows to create handler that act differently on -// errors or allow to log errors. Also note that the handler returned by the +// create a handler for a custom registry or anything that implements the +// Deliverer interface. It also allows to create handlers that act differently +// on errors or allow to log errors. Also note that the handler returned by the // Handler function is already instrumented with some HTTP metrics. You can call // UninstrumentedHandler to get a handler for the DefaultRegistry that is not // instrumented, or you can use InstrumentHandler to instrument any diff --git a/prometheus/example_clustermanager_test.go b/prometheus/example_clustermanager_test.go index 581f922..260c1b5 100644 --- a/prometheus/example_clustermanager_test.go +++ b/prometheus/example_clustermanager_test.go @@ -87,12 +87,12 @@ func (c *ClusterManager) Collect(ch chan<- prometheus.Metric) { // a variable label "host", since we want to partition the collected metrics by // host. Since all Descs created in this way are consistent across instances, // with a guaranteed distinction by the "zone" label, we can register different -// ClusterManager with the same registry. +// ClusterManager instances with the same registry. func NewClusterManager(zone string) *ClusterManager { return &ClusterManager{ Zone: zone, OOMCountDesc: prometheus.NewDesc( - "clustermanager_oom_count", + "clustermanager_oom_crashes_total", "Number of OOM crashes.", []string{"host"}, prometheus.Labels{"zone": zone}, @@ -106,7 +106,7 @@ func NewClusterManager(zone string) *ClusterManager { } } -func ExampleCollector_clustermanager() { +func ExampleCollector() { workerDB := NewClusterManager("db") workerCA := NewClusterManager("ca") diff --git a/prometheus/push/examples_test.go b/prometheus/push/examples_test.go index 5fa27d1..1684819 100644 --- a/prometheus/push/examples_test.go +++ b/prometheus/push/examples_test.go @@ -23,7 +23,7 @@ import ( func ExampleCollectors() { completionTime := prometheus.NewGauge(prometheus.GaugeOpts{ - Name: "db_backup_last_completion_time", + Name: "db_backup_last_completion_timestamp_seconds", Help: "The timestamp of the last succesful completion of a DB backup.", }) completionTime.Set(float64(time.Now().Unix())) @@ -40,7 +40,7 @@ func ExampleRegistry() { registry := prometheus.NewRegistry() completionTime := prometheus.NewGauge(prometheus.GaugeOpts{ - Name: "db_backup_last_completion_time", + Name: "db_backup_last_completion_timestamp_seconds", Help: "The timestamp of the last succesful completion of a DB backup.", }) registry.MustRegister(completionTime) diff --git a/prometheus/registry.go b/prometheus/registry.go index 1d1b57d..9c94cf3 100644 --- a/prometheus/registry.go +++ b/prometheus/registry.go @@ -146,10 +146,11 @@ func MustRegister(cs ...Collector) { // returns the Collector, unless an equal Collector was registered before, in // which case that Collector is returned. // -// RegisterOrGet is merely a convenience function for the implementation as -// described in the documentation for AlreadyRegisteredError. As the use case is -// relatively rare, this function is DEPRECATED and will be removed in a future -// version of this package to clean up the namespace. +// Deprecated: RegisterOrGet is merely a convenience function for the +// implementation as described in the documentation for +// AlreadyRegisteredError. As the use case is relatively rare, this function +// will be removed in a future version of this package to clean up the +// namespace. func RegisterOrGet(c Collector) (Collector, error) { if err := Register(c); err != nil { if are, ok := err.(AlreadyRegisteredError); ok { @@ -163,7 +164,8 @@ func RegisterOrGet(c Collector) (Collector, error) { // MustRegisterOrGet behaves like RegisterOrGet but panics instead of returning // an error. // -// It is DEPRECATED for the same reason RegisterOrGet is. See there for details. +// Deprecated: This is deprecated for the same reason RegisterOrGet is. See +// there for details. func MustRegisterOrGet(c Collector) Collector { c, err := RegisterOrGet(c) if err != nil { @@ -187,8 +189,7 @@ func Unregister(c Collector) bool { // It's a shortcut for DefaultRegistry.SetInjectionHook(hook). See there for // more details. // -// This function is DEPRECATED and will be removed in a future version of this -// package. In the rare cases this call is needed, users should simply call +// Deprecated: In the rare cases this call is needed, users should simply call // DefaultRegistry.SetInjectionHook directly. func SetMetricFamilyInjectionHook(hook func() []*dto.MetricFamily) { DefaultRegistry.SetInjectionHook(hook)