cmd/go: clarify test -run and -bench pattern matching

Make it clearer that -test=X/Y runs all the tests matching X,
even if they don't have sub-tests matching Y.

Fixes #20589.

Change-Id: Ic27e89e748d60f67b50c68445ec0480066bdf207
Reviewed-on: https://go-review.googlesource.com/46030
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/cmd/go/alldocs.go

@@ -1417,12 +1417,17 @@
 // control the execution of any test:
 //
 // 	-bench regexp
-// 	    Run (sub)benchmarks matching a regular expression.
-// 	    The given regular expression is split into smaller ones by
-// 	    top-level '/', where each must match the corresponding part of a
-// 	    benchmark's identifier.
-// 	    By default, no benchmarks run. To run all benchmarks,
-// 	    use '-bench .' or '-bench=.'.
+// 	    Run only those benchmarks matching a regular expression.
+// 	    By default, no benchmarks are run.
+// 	    To run all benchmarks, use '-bench .' or '-bench=.'.
+// 	    The regular expression is split by unbracketed slash (/)
+// 	    characters into a sequence of regular expressions, and each
+// 	    part of a benchmark's identifier must match the corresponding
+// 	    element in the sequence, if any. Possible parents of matches
+// 	    are run with b.N=1 to identify sub-benchmarks. For example,
+// 	    given -bench=X/Y, top-level benchmarks matching X are run
+// 	    with b.N=1 to find any sub-benchmarks matching Y, which are
+// 	    then run in full.
 //
 // 	-benchtime t
 // 	    Run enough iterations of each benchmark to take t, specified
@@ -1479,9 +1484,13 @@
 //
 // 	-run regexp
 // 	    Run only those tests and examples matching the regular expression.
-// 	    For tests the regular expression is split into smaller ones by
-// 	    top-level '/', where each must match the corresponding part of a
-// 	    test's identifier.
+// 	    For tests, the regular expression is split by unbracketed slash (/)
+// 	    characters into a sequence of regular expressions, and each part
+// 	    of a test's identifier must match the corresponding element in
+// 	    the sequence, if any. Note that possible parents of matches are
+// 	    run too, so that -run=X/Y matches and runs and reports the result
+// 	    of all tests matching X, even those without sub-tests matching Y,
+// 	    because it must run them to look for those sub-tests.
 //
 // 	-short
 // 	    Tell long-running tests to shorten their run time.

src/cmd/go/internal/test/test.go

@@ -142,12 +142,17 @@ control the execution of any test:
 
 const testFlag2 = `
 	-bench regexp
-	    Run (sub)benchmarks matching a regular expression.
-	    The given regular expression is split into smaller ones by
-	    top-level '/', where each must match the corresponding part of a
-	    benchmark's identifier.
-	    By default, no benchmarks run. To run all benchmarks,
-	    use '-bench .' or '-bench=.'.
+	    Run only those benchmarks matching a regular expression.
+	    By default, no benchmarks are run. 
+	    To run all benchmarks, use '-bench .' or '-bench=.'.
+	    The regular expression is split by unbracketed slash (/)
+	    characters into a sequence of regular expressions, and each
+	    part of a benchmark's identifier must match the corresponding
+	    element in the sequence, if any. Possible parents of matches
+	    are run with b.N=1 to identify sub-benchmarks. For example,
+	    given -bench=X/Y, top-level benchmarks matching X are run
+	    with b.N=1 to find any sub-benchmarks matching Y, which are
+	    then run in full.
 
 	-benchtime t
 	    Run enough iterations of each benchmark to take t, specified
@@ -204,9 +209,13 @@ const testFlag2 = `
 
 	-run regexp
 	    Run only those tests and examples matching the regular expression.
-	    For tests the regular expression is split into smaller ones by
-	    top-level '/', where each must match the corresponding part of a
-	    test's identifier.
+	    For tests, the regular expression is split by unbracketed slash (/)
+	    characters into a sequence of regular expressions, and each part
+	    of a test's identifier must match the corresponding element in
+	    the sequence, if any. Note that possible parents of matches are
+	    run too, so that -run=X/Y matches and runs and reports the result
+	    of all tests matching X, even those without sub-tests matching Y,
+	    because it must run them to look for those sub-tests.
 
 	-short
 	    Tell long-running tests to shorten their run time.