testing: Logf's documentation is not precise

[yaojingguo]

1. What version of Go are you using (go version)?

go version go1.6.2 linux/amd64

Logf's documentation says:

Logf formats its arguments according to the format, analogous to
Printf, and records the text in the error log. For tests, the text
will be printed only if the test fails or the -test.v flag is set.
For benchmarks, the text is always printed to avoid having
performance depend on the value of the -test.v flag.

Consider this code:

package test

import (
    "testing"
)

func TestLog(t *testing.T) {
    t.Logf("text")
    t.Logf("text\n")
}

Running the tet case with "go test -v -run TestLog" produces::

=== RUN   TestLog
--- PASS: TestLog (0.00s)
    log_test.go:8: text
    log_test.go:9: text
PASS
ok      github.com/yaojingguo/test  0.001s

t.Logf("text") and t.Logf("text\n") produces the same result. So it
can be concluded that Logf appends a new line to a string without
a ending new line. I think that it is better to mention this behavior
in Logf's documentation.

[0xmohit]

The current documentation does mention that; however, it could have been more clear.

log.Printf says:

Printf calls Output to print to the standard logger. Arguments are handled
in the manner of fmt.Printf.

and log.Output says:

Output writes the output for a logging event. The string s contains the text
to print after the prefix specified by the flags of the Logger. A newline is
appended if the last character of s is not already a newline. Calldepth is
the count of the number of frames to skip when computing the file name and
line number if Llongfile or Lshortfile is set; a value of 1 will print the
details for the caller of Output.

Maybe analogous to Printf could use log.Printf instead of Printf thereby avoiding confusion with fmt.Printf.

[yaojingguo]

testing.T's Logf formats a message with decorate function. decorate formats a message in a different way than log.Printf. For example, it indents the the first line of the message with a tab. And it intents second and subsequent lines with two tabs, etc.

And testing.B.Logf's documentation has the same problem as testing.T.Logf.

[gopherbot]

CL https://golang.org/cl/31255 mentions this issue.