Closed
Description
Go version
tip
Output of go env in your module/workspace:
n/aWhat 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