testing: document that flag.Parse is not called when TestMain runs

Fixes #9825.

Change-Id: Id7eeaa14c26201db34db0820371c92a63af485b0
Reviewed-on: https://go-review.googlesource.com/7604
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/testing/testing.go b/src/testing/testing.go
index 966b5466b711faaf7d186a45ff167394fd7b8ff2..51631238aaa05ff5abc687267a868df5b1812e54 100644 (file)
--- a/src/testing/testing.go
+++ b/src/testing/testing.go
@@ -130,13 +130,17 @@
 // then the generated test will call TestMain(m) instead of running the tests
 // directly. TestMain runs in the main goroutine and can do whatever setup
 // and teardown is necessary around a call to m.Run. It should then call
-// os.Exit with the result of m.Run.
+// os.Exit with the result of m.Run. When TestMain is called, flag.Parse has
+// not been run. If TestMain depends on command-line flags, including those
+// of the testing package, it should call flag.Parse explicitly.
 //
-// The minimal implementation of TestMain is:
+// A simple implementation of TestMain is:
 //
-//     func TestMain(m *testing.M) { os.Exit(m.Run()) }
+//     func TestMain(m *testing.M) {
+//             flag.Parse()
+//             os.Exit(m.Run())
+//     }
 //
-// In effect, that is the implementation used when no TestMain is explicitly defined.
 package testing
 
 import (