testing: the overview documentation on (*T) Run is unclear

[opennota]

The package documentation says that

// Run does not return until parallel subtests have completed

But that means that in the example above (see below) the tests aren't run in parallel, because "Run does not return", which I take to mean that the first Run blocks (and then the second too, etc):

//     func TestGroupedParallel(t *testing.T) {
//         for _, tc := range tests {
//             tc := tc // capture range variable
//             t.Run(tc.Name, func(t *testing.T) {
//                 t.Parallel()
//                 ...
//             })
//         }
//     }

[toothrot]

@opennota I feel like the documentation for T.Run itself is fairly clear on this behavior:

https://pkg.go.dev/testing?tab=doc#T.Run

Run runs f as a subtest of t called name. It runs f in a separate goroutine and blocks until f returns or calls t.Parallel to become a parallel test. Run reports whether f succeeded (or at least did not fail before calling t.Parallel).
Run may be called simultaneously from multiple goroutines, but all such calls must return before the outer test function for t returns.

Do you have a suggestion for improving this?

Also, if you're curious, you can see the go running the tests here: https://github.com/golang/go/blob/go1.13.4/src/testing/testing.go#L960

[opennota]

This is clear enough:

blocks until f returns or calls t.Parallel to become a parallel test.

but the package documentation which I'm talking about comes first and if one reads from the start can confuse him.

[toothrot]

/cc @mpvl @josharian