testing: improve the text of the b.Loop documentation

[cespare]

Go version

tip

Output of go env in your module/workspace:

n/a

What did you do?

The documentation for b.Loop (upcoming in Go 1.24) currently reads:

// Loop returns true until b.N calls has been made to it.
//
// A benchmark should either use Loop or contain an explicit loop from 0 to b.N, but not both.
// After the benchmark finishes, b.N will contain the total number of calls to op, so the benchmark
// may use b.N to compute other average metrics.
//
// The parameters and results of function calls inside the body of "for b.Loop() {...}" are guaranteed
// not to be optimized away.
// Also, the local loop scaling for b.Loop ensures the benchmark function containing the loop will only
// be executed once, i.e. for such construct:
//
//	testing.Benchmark(func(b *testing.B) {
//			...(setup)
//			for b.Loop() {
//				...(benchmark logic)
//			}
//			...(clean-up)
//	}
//
// The ...(setup) and ...(clean-up) logic will only be executed once.
// Also benchtime=Nx (N>1) will result in exactly N executions instead of N+1 for b.N style loops.
func (b *B) Loop() bool

In my opinion this still needs quite a bit of polish. Some of the issues:

• s/has/have/ in the first sentence
• s/will contain/contains/, s/will only be/is only/g, s/will result/results/
• What is "calls to op"?
• I feel like "local loop scaling" is non-obvious.
• "i.e. for such construct" needs rephrasing
• Comma after "Also" (but also that is repetitive).
• s/benchtime/-benchtime/

I feel like the best fix, though, is not a bunch of spot tweaks but a more comprehensive overhaul. I can take a stab at it but I think someone else would be better suited. (Writing good docs is hard!)

What did you see happen?

n/a

What did you expect to see?

n/a

[gabyhelp]

Related Issues

• testing: add testing.B.Loop for iteration #61515 (closed)
• testing: clarify that b.N does not change during execution of the benchmark function #67137 (closed)

Related Code Changes

• testing: improve documentation, examples, release notes for

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[cagedmantis]

cc @adonovan @neild JunyangShao

[cespare]

This is fixed by CL 635895.

[gopherbot]

Change https://go.dev/cl/635895 mentions this issue: testing: improve B.Loop docs, use B.Loop in examples