You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
testing: improve the text of the b.Loop documentation #70787
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!)
Activity
gabyhelp commentedon Dec 11, 2024
Related Issues
Related Code Changes
(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)
cagedmantis commentedon Dec 11, 2024
cc @adonovan @neild JunyangShao
cespare commentedon Dec 13, 2024
This is fixed by CL 635895.
gopherbot commentedon Dec 13, 2024
Change https://go.dev/cl/635895 mentions this issue:
testing: improve B.Loop docs, use B.Loop in examples