Improve various comments

Signed-off-by: beorn7 <beorn@grafana.com>

prometheus/testutil/lint.go

@@ -20,9 +20,9 @@ import (
 	"github.com/prometheus/client_golang/prometheus/testutil/promlint"
 )
 
-// CollectAndLint registers the provided Collector with a newly created
-// pedantic Registry. It then does the same as GatherAndLint, gathering the
-// metrics from the pedantic Registry.
+// CollectAndLint registers the provided Collector with a newly created pedantic
+// Registry. It then calls GatherAndLint with that Registry and with the
+// provided metricNames.
 func CollectAndLint(c prometheus.Collector, metricNames ...string) ([]promlint.Problem, error) {
 	reg := prometheus.NewPedanticRegistry()
 	if err := reg.Register(c); err != nil {

prometheus/testutil/lint_test.go

@@ -63,8 +63,9 @@ func TestCollectAndLintBad(t *testing.T) {
 	if len(problems) < 5 {
 		// The exact nature of the lint problems found is tested within
 		// the promlint package itself. Here we only want to make sure
-		// that the collector successfully hit the linter and got enough
-		// problems flagged.
+		// that the collector successfully hits the linter and that at
+		// least the five problems that the linter could recognize at
+		// the time of writing this test are flagged.
 		t.Error("Not enough lint problems found.")
 	}
 }

prometheus/testutil/promlint/promlint.go

@@ -29,6 +29,11 @@ import (
 // A Linter is a Prometheus metrics linter.  It identifies issues with metric
 // names, types, and metadata, and reports them to the caller.
 type Linter struct {
+	// The linter will read metrics in the Prometheus text format from r and
+	// then lint it, _and_ it will lint the metrics provided directly as
+	// MetricFamily proto messages in mfs. Note, however, that the current
+	// constructor functions New and NewWithMetricFamilies only ever set one
+	// of them.
 	r   io.Reader
 	mfs []*dto.MetricFamily
 }

prometheus/testutil/testutil.go

@@ -140,8 +140,8 @@ func CollectAndCount(c prometheus.Collector) int {
 }
 
 // CollectAndCompare registers the provided Collector with a newly created
-// pedantic Registry. It then does the same as GatherAndCompare, gathering the
-// metrics from the pedantic Registry.
+// pedantic Registry. It then calls GatherAndCompare with that Registry and with
+// the provided metricNames.
 func CollectAndCompare(c prometheus.Collector, expected io.Reader, metricNames ...string) error {
 	reg := prometheus.NewPedanticRegistry()
 	if err := reg.Register(c); err != nil {