Skip to content

testing: improve the text of the b.Loop documentation #70787

Closed

Description

@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

Activity

  1. gabyhelp commented on Dec 11, 2024

    @gabyhelp
  2. added
    NeedsInvestigationSomeone must examine and confirm this is a valid issue and not a duplicate of an existing one.
    on Dec 11, 2024
  3. added this to the Go1.24 milestone on Dec 11, 2024
  4. cagedmantis commented on Dec 11, 2024

    @cagedmantis
    Contributor
  5. cespare commented on Dec 13, 2024

    @cespare
    ContributorAuthor

    This is fixed by CL 635895.

  6. gopherbot commented on Dec 13, 2024

    @gopherbot
    Contributor

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

  7. locked and limited conversation to collaborators on Dec 16, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationIssues describing a change to documentation.FrozenDueToAgeNeedsInvestigationSomeone must examine and confirm this is a valid issue and not a duplicate of an existing one.

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions