slog: clarify documentation
Change-Id: I00236e14c150236b538f57cb36e16aad138dbbcf
Reviewed-on: https://go-review.googlesource.com/c/exp/+/443855
Reviewed-by: Alan Donovan <adonovan@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
diff --git a/slog/handler.go b/slog/handler.go
index 3200160..6ec0d04 100644
--- a/slog/handler.go
+++ b/slog/handler.go
@@ -30,13 +30,14 @@
Enabled(Level) bool
// Handle handles the Record.
+ // It will only be called if Enabled returns true.
// Handle methods that produce output should observe the following rules:
// - If r.Time is the zero time, ignore the time.
// - If an Attr's key is the empty string, ignore the Attr.
Handle(r Record) error
// WithAttrs returns a new Handler whose attributes consist of
- // the receiver's attributes concatenated with the arguments.
+ // both the receiver's attributes and the arguments.
// The Handler owns the slice: it may retain, modify or discard it.
WithAttrs(attrs []Attr) Handler
diff --git a/slog/logger.go b/slog/logger.go
index b956fa8..11300f2 100644
--- a/slog/logger.go
+++ b/slog/logger.go
@@ -77,9 +77,9 @@
// Context returns l's context.
func (l Logger) Context() context.Context { return l.ctx }
-// With returns a new Logger whose handler's attributes are a concatenation of
-// l's attributes and the given arguments, converted to Attrs as in
-// [Logger.Log].
+// With returns a new Logger that includes the given arguments, converted to
+// Attrs as in [Logger.Log]. The new Logger's handler is the result of calling
+// WithAttrs on the receiver's handler.
func (l Logger) With(args ...any) Logger {
var (
attr Attr
