testing: clarify rules for concurrent t.Run calls

Apparently, "all such calls must happen" means that the t.Run call
must *return* before the outer test function returns, or the calls
will cause a data race on t.ran.

Clarify the docs.

Fixes #20339

Change-Id: I191a9af2a9095be1e0aaf10b79c30e00a9c495cb
Reviewed-on: https://go-review.googlesource.com/47150Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/testing/benchmark.go

@@ -482,7 +482,7 @@ func (ctx *benchContext) processBench(b *B) {
 // least once will not be measured itself and will be called once with N=1.
 //
 // Run may be called simultaneously from multiple goroutines, but all such
-// calls must happen before the outer benchmark function for b returns.
+// calls must return before the outer benchmark function for b returns.
 func (b *B) Run(name string, f func(b *B)) bool {
 	// Since b has subbenchmarks, we will no longer run it as a benchmark itself.
 	// Release the lock and acquire it on exit to ensure locks stay paired.

src/testing/testing.go

@@ -760,7 +760,7 @@ func tRunner(t *T, fn func(t *T)) {
 // have completed.
 //
 // Run may be called simultaneously from multiple goroutines, but all such calls
-// must happen before the outer test function for t returns.
+// must return before the outer test function for t returns.
 func (t *T) Run(name string, f func(t *T)) bool {
 	atomic.StoreInt32(&t.hasSub, 1)
 	testName, ok, _ := t.context.match.fullName(&t.common, name)