testing: clarity of -timeout flag

[vcabbage]

This is directly related to #20090, opening a new issue because I'm not sure whether closed issues are supposed to be reopened.

The description of the -timeout flag has changed twice for Go 1.9. The first change (done by me) was intended to clarify that the timeout applies per package. The latest revision, referring to "a test binary", is certainly correct, but in my experience many gophers do not know that the tests from each package is executed as a separate test binary. This can be inferred from the help text, but it's not explicit and likely to be ambiguous to many.

There may well be a better description than what I provided. I'd just like for the documentation to be clear without needing to understand exactly how test binaries are built and executed.

Original Text:

-timeout t
If a test runs longer than t, panic.
The default is 10 minutes (10m).

https://golang.org/cl/45816:

-timeout d
If the cumulative test time for a package runs longer than
duration d, panic. Timeout is disabled if set to 0.
The default is 10 minutes (10m).

https://golang.org/cl/47571:

-timeout d
If a test binary runs longer than duration d, panic.
The default is 10 minutes (10m).

Notes:

• Emphasis added.
• The "Timeout is disabled if set to 0" text can be ignored. It was a mistake on my part.

[vcabbage]

/cc @rsc

[rsc]

This appears to be about the phrase "test binary". That term is defined at the top of 'go help test' and used in multiple places throughout the test docs. It's impossible to make every help output stand alone. If one reads 'go help testflag' and don't understand what a test binary is, the natural next step would be 'go help test'? Or Google [test binary golang], whose first result is https://golang.org/cmd/go/. Given that it's a defined term, I don't think it's ambiguous, and I don't have a better one ('package test' is the obvious candidate but I think many people would expect that there are many package tests - every func TestFoo - for a given package; test binary is more clearly not a single test function).