log: update the documentation to clarify the behavior

R=rsc, PeterGo
CC=golang-dev
https://golang.org/cl/2519043

src/pkg/log/log.go

@@ -21,7 +21,7 @@ import (
 	"time"
 )
 
-// These flags define the output Loggers produce.
+// These flags define which text to prefix to each log entry generated by the Logger.
 const (
 	// Bits or'ed together to control what's printed. There is no control over the
 	// order they appear (the order listed here) or the format they present (as
@@ -125,9 +125,12 @@ func (l *Logger) formatHeader(buf *bytes.Buffer, ns int64, calldepth int) {
 	}
 }
 
-// Output writes the output for a logging event.  The string s contains the text to print after
+// Output writes the output for a logging event.  The string s contains
-// the time stamp;  calldepth is used to recover the PC.  It is provided for generality, although
+// the text to print after the prefix specified by the flags of the
-// at the moment on all pre-defined paths it will be 2.
+// Logger.  A newline is appended if the last character of s is not
+// already a newline.  Calldepth is used to recover the PC and is
+// provided for generality, although at the moment on all pre-defined
+// paths it will be 2.
 func (l *Logger) Output(calldepth int, s string) os.Error {
 	now := time.Nanoseconds() // get this early.
 	buf := new(bytes.Buffer)
@@ -140,15 +143,18 @@ func (l *Logger) Output(calldepth int, s string) os.Error {
 	return err
 }
 
-// Printf prints to the logger in the manner of fmt.Printf.
+// Printf calls l.Output to print to the logger.
+// Arguments are handled in the manner of fmt.Printf.
 func (l *Logger) Printf(format string, v ...interface{}) {
 	l.Output(2, fmt.Sprintf(format, v...))
 }
 
-// Print prints to the logger in the manner of fmt.Print.
+// Print calls l.Output to print to the logger.
+// Arguments are handled in the manner of fmt.Print.
 func (l *Logger) Print(v ...interface{}) { l.Output(2, fmt.Sprint(v...)) }
 
-// Println prints to the logger in the manner of fmt.Println.
+// Println calls l.Output to print to the logger.
+// Arguments are handled in the manner of fmt.Println.
 func (l *Logger) Println(v ...interface{}) { l.Output(2, fmt.Sprintln(v...)) }
 
 // SetOutput sets the output destination for the standard logger.
@@ -168,17 +174,20 @@ func SetPrefix(prefix string) {
 
 // These functions write to the standard logger.
 
-// Print prints to the standard logger in the manner of fmt.Print.
+// Print calls Output to print to the standard logger.
+// Arguments are handled in the manner of fmt.Print.
 func Print(v ...interface{}) {
 	std.Output(2, fmt.Sprint(v...))
 }
 
-// Printf prints to the standard logger in the manner of fmt.Printf.
+// Printf calls Output to print to the standard logger.
+// Arguments are handled in the manner of fmt.Printf.
 func Printf(format string, v ...interface{}) {
 	std.Output(2, fmt.Sprintf(format, v...))
 }
 
-// Println prints to the standard logger in the manner of fmt.Println.
+// Println calls Output to print to the standard logger.
+// Arguments are handled in the manner of fmt.Println.
 func Println(v ...interface{}) {
 	std.Output(2, fmt.Sprintln(v...))
 }