testing: improve the documentation around b.N

Fixes #67137

- Make it clear the benchmark function is called multiple times.
- Demonstrate range over int.

Change-Id: I7e993d938b0351012cdd4aed8528951e0ad406ae
Reviewed-on: https://go-review.googlesource.com/c/go/+/582835
Auto-Submit: Alan Donovan <adonovan@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Damien Neil <dneil@google.com>

diff --git a/src/testing/testing.go b/src/testing/testing.go
index 2289c6717f1d719c0f8a47bca2f182a31bb61927..60f0c23137d6f03fa0a87368241453c2f2d540d0 100644 (file)
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -72,14 +72,15 @@
 // A sample benchmark function looks like this:
 //
 //     func BenchmarkRandInt(b *testing.B) {
-//         for i := 0; i < b.N; i++ {
+//         for range b.N {
 //             rand.Int()
 //         }
 //     }
 //
 // The benchmark function must run the target code b.N times.
-// During benchmark execution, b.N is adjusted until the benchmark function lasts
-// long enough to be timed reliably. The output
+// It is called multiple times with b.N adjusted until the
+// benchmark function lasts long enough to be timed reliably.
+// The output
 //
 //     BenchmarkRandInt-8      68453040                17.8 ns/op
 //
@@ -91,7 +92,7 @@
 //     func BenchmarkBigLen(b *testing.B) {
 //         big := NewBig()
 //         b.ResetTimer()
-//         for i := 0; i < b.N; i++ {
+//         for range b.N {
 //             big.Len()
 //         }
 //     }