Merge pull request #20566 from mjibson/log-docs

util/log: cleanup top-level godoc comments

pkg/util/log/doc.go

@@ -15,40 +15,59 @@
 
 // This code originated in the github.com/golang/glog package.
 
-// Package log implements logging analogous to the Google-internal C++ INFO/ERROR/V setup.
-// It provides functions Info, Warning, Error, Fatal, plus formatting variants such as
-// Infof. It also provides V-style logging and adaptions for use as a structured
-// logging engine.
+// Package log implements logging.
+// There are three logging styles: named, V-style, events.
 //
-// Basic examples:
+// Named Functions
 //
-//	log.Info("Prepare to repel boarders")
+// The functions Info, Warning, Error, and Fatal log their arguments at the
+// specified level. All include formatting variants like Infof.
 //
-//	log.Fatal("Initialization failed", err)
+// Examples:
 //
-//  // Log with context.
-//  log.Infoc(context, "client error: %s", err)
+//	log.Info(ctx, "Prepare to repel boarders")
+//	log.Fatal(ctx, "Initialization failed", err)
+//	log.Infof(ctx, "client error: %s", err)
 //
-// See the documentation for the V function for an explanation of these examples:
+// V-Style
+//
+// The V functions can be used to selectively enable logging at a call
+// site. Invoking the binary with --verbosity=N will enable V functions
+// at level N or higher. Invoking the binary with --vmodule="glob=N" will
+// enable V functions at level N or higher with a filename matching glob.
+//
+// Examples:
 //
 //	if log.V(2) {
-//		log.Info("Starting transaction...")
+//		log.Info(ctx, "Starting transaction...")
 //	}
 //
+// Events
+//
+// The Event functions log messages to an existing trace if one exists. The
+// VEvent functions logs the message to a trace and also the log file based
+// on the V level.
+//
+// Examples:
+//
+//	log.VEventf(ctx, 2, "client error; %s", err)
+//
+// Output
+//
 // Log output is buffered and written periodically using Flush. Programs
 // should call Flush before exiting to guarantee all log output is written.
 //
 // By default, all log statements write to files in a temporary directory.
 // This package provides several flags that modify this behavior.
-// These are provided via the pflags library; see InitFlags.
+// These are provided via the util/log/logflags package; see InitFlags.
 //
-//	--logtostderr=LEVEL
-//		Logs are written to standard error as well as to files.
+//  --logtostderr=LEVEL
+//    Logs are written to standard error as well as to files.
 //    Entries with severity below LEVEL are not written to stderr.
 //    "true" and "false" are also supported (everything / nothing).
-//	--log-dir="..."
-//		Log files will be written to this directory instead of the
-//		default target directory.
+//  --log-dir="..."
+//    Log files will be written to this directory instead of the
+//    default target directory.
 //  --log-file-verbosity=LEVEL
 //    Entries with severity below LEVEL are not written to the log file.
 //    "true" and "false" are also supported (everything / nothing).
@@ -57,22 +76,26 @@
 //  --log-dir-max-size=N
 //    Log files are removed after log directory reaches that size.
 //
-//	Other flags provide aids to debugging.
-//
-//	--log-backtrace-at=""
-//		When set to a file and line number holding a logging statement,
-//		such as
-//			-log_backtrace_at=gopherflakes.go:234
-//		a stack trace will be written to the Info log whenever execution
-//		hits that statement. (Unlike with --vmodule, the ".go" must be
-//		present.)
-//	--verbosity=0
-//		Enable V-leveled logging at the specified level.
-//	--vmodule=""
-//		The syntax of the argument is a comma-separated list of pattern=N,
-//		where pattern is a literal file name (minus the ".go" suffix) or
-//		"glob" pattern and N is a V level. For instance,
-//			-vmodule=gopher*=3
-//		sets the V level to 3 in all Go files whose names begin "gopher".
+// Other flags provide aids to debugging.
+//
+//  --log-backtrace-at=""
+//    When set to a file and line number holding a logging statement,
+//    such as
+//      -log_backtrace_at=gopherflakes.go:234
+//    a stack trace will be written to the Info log whenever execution
+//    hits that statement. (Unlike with --vmodule, the ".go" must be
+//    present.)
+//  --verbosity=0
+//    Enable V-leveled logging at the specified level.
+//  --vmodule=""
+//    The syntax of the argument is a comma-separated list of pattern=N,
+//    where pattern is a literal file name (minus the ".go" suffix) or
+//    "glob" pattern and N is a V level. For instance,
+//      --vmodule=gopher*=3
+//    sets the V level to 3 in all Go files whose names begin "gopher".
+//
+// Protobuf
+//
+// Autogenerated:
 //
 package log