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>

1 files changed, 5 insertions, 4 deletions

diff --git a/src/testing/testing.go b/src/testing/testing.go
index 2289c6717f..60f0c23137 100644
--- 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()
 //	    }
 //	}