runtime/metrics: add ordering line to supported metrics docs

This change adds an additional line explaining the ordering of the
supported metrics list. It's also necessary to ensure "Supported
metrics" is displayed by godoc as a proper header.

This modification does mean the description test, that ensures
descriptions line up with documentation, needs to change slightly
so it it doesn't read this new line as documentation. Make this
new line the line the test uses to decide when to begin.

Change-Id: I654c1c20e97a80ea79c8eb864445153ce91950bf
Reviewed-on: https://go-review.googlesource.com/c/go/+/275852
Run-TryBot: Michael Knyszek <mknyszek@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Trust: Michael Knyszek <mknyszek@google.com>
Reviewed-by: Michael Pratt <mpratt@google.com>

diff --git a/src/runtime/metrics/description_test.go b/src/runtime/metrics/description_test.go
index 448639ee777ef9718bb874585a2712b3cafd538c..fd1fd46efc04da543e7ae3b8a82b5779902962e0 100644 (file)
--- a/src/runtime/metrics/description_test.go
+++ b/src/runtime/metrics/description_test.go
@@ -43,7 +43,7 @@ func extractMetricDocs(t *testing.T) map[string]string {
                line := strings.TrimSpace(s.Text())
                switch state {
                case stateSearch:
-                       if line == "Supported metrics" {
+                       if line == "Below is the full list of supported metrics, ordered lexicographically." {
                                state = stateNextMetric
                        }
                case stateNextMetric:

diff --git a/src/runtime/metrics/doc.go b/src/runtime/metrics/doc.go
index 42b5bc372431ff7fd770931afff9e9e4c2c82e07..05a887e4f40e240e62e7ddc0ad1e8df2b05dd0e1 100644 (file)
--- a/src/runtime/metrics/doc.go
+++ b/src/runtime/metrics/doc.go
@@ -44,6 +44,8 @@ the documentation of the Name field of the Description struct.
 
 Supported metrics
 
+Below is the full list of supported metrics, ordered lexicographically.
+
        /gc/cycles/automatic:gc-cycles
                Count of completed GC cycles generated by the Go runtime.