Fix a number of doc comments and similar nits

prometheus/collector.go

@@ -50,9 +50,9 @@ type Collector interface {
 	Collect(chan<- Metric)
 }
 
-// selfCollector implements Collector for a single Metric so that that the
+// selfCollector implements Collector for a single Metric so that the Metric
-// Metric collects itself. Add it as an anonymous field to a struct that
+// collects itself. Add it as an anonymous field to a struct that implements
-// implements Metric, and call Init with the Metric itself as an argument.
+// Metric, and call init with the Metric itself as an argument.
 type selfCollector struct {
 	self Metric
 }

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.
+	// Deprecated: Use NewConstMetric to create a counter for an external
-	// TODO(beorn7): Remove.
+	// value. A Counter should never be set.
 	Set(float64)
 	// Inc increments the counter by 1.
 	Inc()

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
+// create a handler for a custom registry or anything that implements the
-// Deliverer interface. It also allows to create handler that act differently on
+// Deliverer interface. It also allows to create handlers that act differently
-// errors or allow to log errors. Also note that the handler returned by the
+// 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

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")
 

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)

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
+// Deprecated: RegisterOrGet is merely a convenience function for the
-// described in the documentation for AlreadyRegisteredError. As the use case is
+// implementation as described in the documentation for
-// relatively rare, this function is DEPRECATED and will be removed in a future
+// AlreadyRegisteredError. As the use case is relatively rare, this function
-// version of this package to clean up the namespace.
+// 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
+// Deprecated: In the rare cases this call is needed, users should simply call
-// package. In the rare cases this call is needed, users should simply call
 // DefaultRegistry.SetInjectionHook directly.
 func SetMetricFamilyInjectionHook(hook func() []*dto.MetricFamily) {
 	DefaultRegistry.SetInjectionHook(hook)