From a36c68f12cdc45f52184b563dab475f340e00dd7 Mon Sep 17 00:00:00 2001
From: Nate Armstrong <naterarmstrong@gmail.com>
Date: Wed, 22 Feb 2023 04:39:41 -0800
Subject: [PATCH] log: improve documentation (#26753)

Add usage examples
---
 log/logger.go | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 log/root.go   | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/log/logger.go b/log/logger.go
index 1549e3285..4e471a22d 100644
--- a/log/logger.go
+++ b/log/logger.go
@@ -116,12 +116,58 @@ type Logger interface {
 	// SetHandler updates the logger to write records to the specified handler.
 	SetHandler(h Handler)
 
-	// Log a message at the given level with context key/value pairs
+	// Log a message at the trace level with context key/value pairs
+	//
+	// # Usage
+	//
+	//	log.Trace("msg")
+	//	log.Trace("msg", "key1", val1)
+	//	log.Trace("msg", "key1", val1, "key2", val2)
 	Trace(msg string, ctx ...interface{})
+
+	// Log a message at the debug level with context key/value pairs
+	//
+	// # Usage Examples
+	//
+	//	log.Debug("msg")
+	//	log.Debug("msg", "key1", val1)
+	//	log.Debug("msg", "key1", val1, "key2", val2)
 	Debug(msg string, ctx ...interface{})
+
+	// Log a message at the info level with context key/value pairs
+	//
+	// # Usage Examples
+	//
+	//	log.Info("msg")
+	//	log.Info("msg", "key1", val1)
+	//	log.Info("msg", "key1", val1, "key2", val2)
 	Info(msg string, ctx ...interface{})
+
+	// Log a message at the warn level with context key/value pairs
+	//
+	// # Usage Examples
+	//
+	//	log.Warn("msg")
+	//	log.Warn("msg", "key1", val1)
+	//	log.Warn("msg", "key1", val1, "key2", val2)
 	Warn(msg string, ctx ...interface{})
+
+	// Log a message at the error level with context key/value pairs
+	//
+	// # Usage Examples
+	//
+	//	log.Error("msg")
+	//	log.Error("msg", "key1", val1)
+	//	log.Error("msg", "key1", val1, "key2", val2)
 	Error(msg string, ctx ...interface{})
+
+	// Log a message at the crit level with context key/value pairs, and then exit.
+	//
+	// # Usage Examples
+	//
+	//	log.Crit("msg")
+	//	log.Crit("msg", "key1", val1)
+	//	log.Crit("msg", "key1", val1, "key2", val2)
 	Crit(msg string, ctx ...interface{})
 }
 
diff --git a/log/root.go b/log/root.go
index 9fb4c5ae0..5a41723c3 100644
--- a/log/root.go
+++ b/log/root.go
@@ -30,31 +30,79 @@ func Root() Logger {
 // runtime.Caller(2) always refers to the call site in client code.
 
 // Trace is a convenient alias for Root().Trace
+//
+// Log a message at the trace level with context key/value pairs
+//
+// # Usage
+//
+//	log.Trace("msg")
+//	log.Trace("msg", "key1", val1)
+//	log.Trace("msg", "key1", val1, "key2", val2)
 func Trace(msg string, ctx ...interface{}) {
 	root.write(msg, LvlTrace, ctx, skipLevel)
 }
 
 // Debug is a convenient alias for Root().Debug
+//
+// Log a message at the debug level with context key/value pairs
+//
+// # Usage Examples
+//
+//	log.Debug("msg")
+//	log.Debug("msg", "key1", val1)
+//	log.Debug("msg", "key1", val1, "key2", val2)
 func Debug(msg string, ctx ...interface{}) {
 	root.write(msg, LvlDebug, ctx, skipLevel)
 }
 
 // Info is a convenient alias for Root().Info
+//
+// Log a message at the info level with context key/value pairs
+//
+// # Usage Examples
+//
+//	log.Info("msg")
+//	log.Info("msg", "key1", val1)
+//	log.Info("msg", "key1", val1, "key2", val2)
 func Info(msg string, ctx ...interface{}) {
 	root.write(msg, LvlInfo, ctx, skipLevel)
 }
 
 // Warn is a convenient alias for Root().Warn
+//
+// Log a message at the warn level with context key/value pairs
+//
+// # Usage Examples
+//
+//	log.Warn("msg")
+//	log.Warn("msg", "key1", val1)
+//	log.Warn("msg", "key1", val1, "key2", val2)
 func Warn(msg string, ctx ...interface{}) {
 	root.write(msg, LvlWarn, ctx, skipLevel)
 }
 
 // Error is a convenient alias for Root().Error
+//
+// Log a message at the error level with context key/value pairs
+//
+// # Usage Examples
+//
+//	log.Error("msg")
+//	log.Error("msg", "key1", val1)
+//	log.Error("msg", "key1", val1, "key2", val2)
 func Error(msg string, ctx ...interface{}) {
 	root.write(msg, LvlError, ctx, skipLevel)
 }
 
 // Crit is a convenient alias for Root().Crit
+//
+// Log a message at the crit level with context key/value pairs, and then exit.
+//
+// # Usage Examples
+//
+//	log.Crit("msg")
+//	log.Crit("msg", "key1", val1)
+//	log.Crit("msg", "key1", val1, "key2", val2)
 func Crit(msg string, ctx ...interface{}) {
 	root.write(msg, LvlCrit, ctx, skipLevel)
 	os.Exit(1)