testing: document that Log and Logf do not usually produce output

The text is printed only if the test fails or -test.v is set.
Document this behavior in the testing package and 'go help test'.
Also put a 'go install' into mkdoc.sh so I don't get tricked by the
process of updating the documentation ever again.

Fixes #5174.

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/8118047

diff --git a/src/cmd/go/doc.go b/src/cmd/go/doc.go
index a8a9b66aa0fffdafa0ab61f76db8c8ea1dd81cb0..498365f83806c0cba08d4a076957b585189410a8 100644 (file)
--- a/src/cmd/go/doc.go
+++ b/src/cmd/go/doc.go
@@ -763,7 +763,8 @@ control the execution of any test:
                If a test runs longer than t, panic.
 
        -v
-           Verbose output: log all tests as they are run.
+           Verbose output: log all tests as they are run. Also print all
+           text from Log and Logf calls even if the test succeeds.
 
 The test binary, called pkg.test where pkg is the name of the
 directory containing the package sources, can be invoked directly

diff --git a/src/cmd/go/mkdoc.sh b/src/cmd/go/mkdoc.sh
index 7768baeb6b9364baa874b2dd1af237ef446ff617..12fd7ba3e7f62e4fc874cb1581be9d332767a60b 100755 (executable)
--- a/src/cmd/go/mkdoc.sh
+++ b/src/cmd/go/mkdoc.sh
@@ -3,6 +3,7 @@
 # Use of this source code is governed by a BSD-style
 # license that can be found in the LICENSE file.
 
+go install # So the next line will produce updated documentation.
 go help documentation > doc.go
 gofmt -w doc.go
 

diff --git a/src/cmd/go/test.go b/src/cmd/go/test.go
index de69efe8f26641ca16ef116410db182b28d969d3..56046a8c712214b9bcc052e08f2fd740705c5216 100644 (file)
--- a/src/cmd/go/test.go
+++ b/src/cmd/go/test.go
@@ -153,7 +153,8 @@ control the execution of any test:
                If a test runs longer than t, panic.
 
        -v
-           Verbose output: log all tests as they are run.
+           Verbose output: log all tests as they are run. Also print all
+           text from Log and Logf calls even if the test succeeds.
 
 The test binary, called pkg.test where pkg is the name of the
 directory containing the package sources, can be invoked directly

diff --git a/src/pkg/testing/testing.go b/src/pkg/testing/testing.go
index d0c759e29260e95876eccb71690c54a7b0018315..c834aa1f7e5406aa41584749e5c91af4e7389d92 100644 (file)
--- a/src/pkg/testing/testing.go
+++ b/src/pkg/testing/testing.go
@@ -246,11 +246,13 @@ func (c *common) log(s string) {
 }
 
 // Log formats its arguments using default formatting, analogous to Println,
-// and records the text in the error log.
+// and records the text in the error log. The text will be printed only if
+// the test fails or the -test.v flag is set.
 func (c *common) Log(args ...interface{}) { c.log(fmt.Sprintln(args...)) }
 
 // Logf formats its arguments according to the format, analogous to Printf,
-// and records the text in the error log.
+// and records the text in the error log. The text will be printed only if
+// the test fails or the -test.v flag is set.
 func (c *common) Logf(format string, args ...interface{}) { c.log(fmt.Sprintf(format, args...)) }
 
 // Error is equivalent to Log followed by Fail.