testing: reference benchmark format spec

This updates the testing package documentation to reference the
specification for the benchmark format, and points users to our
standard tools for working with benchmark data. (It's somewhat
remarkable how widely used benchstat appears to be given that we don't
mention it anywhere!)

Change-Id: Idbb4416d2fde9606ea7e6c15595f3b9e6a38f3b0
Reviewed-on: https://go-review.googlesource.com/c/go/+/357589
Trust: Austin Clements <austin@google.com>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/testing/testing.go b/src/testing/testing.go
index d03c0b1cf9b5a3c4ab286d36f00825e6085c0345..6fb1a71d4335f3eb6fca09f19b662243dfc608e5 100644 (file)
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -75,6 +75,14 @@
 //         })
 //     }
 //
+// A detailed specification of the benchmark results format is given
+// in https://golang.org/design/14313-benchmark-format.
+//
+// There are standard tools for working with benchmark results at
+// https://golang.org/x/perf/cmd.
+// In particular, https://golang.org/x/perf/cmd/benchstat performs
+// statistically robust A/B comparisons.
+//
 // Examples
 //
 // The package also runs and verifies example code. Example functions may