slog: documentation clarifications
- Clarify use of Handler.With methods.
- Document that Handler.Handle should ignore a zero PC.
- Fix a typo.
Change-Id: I4bab18557f76058a6d63d913d5a0a81a4ce8825a
Reviewed-on: https://go-review.googlesource.com/c/exp/+/474155
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
diff --git a/slog/example_custom_levels_test.go b/slog/example_custom_levels_test.go
index b701b44..3d64cc6 100644
--- a/slog/example_custom_levels_test.go
+++ b/slog/example_custom_levels_test.go
@@ -33,7 +33,7 @@
Level: LevelTrace,
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
- // Remove time from the output for predicable test output.
+ // Remove time from the output for predictable test output.
if a.Key == slog.TimeKey {
return slog.Attr{}
}
diff --git a/slog/handler.go b/slog/handler.go
index 60d58bb..3818470 100644
--- a/slog/handler.go
+++ b/slog/handler.go
@@ -25,6 +25,9 @@
// Any of the Handler's methods may be called concurrently with itself
// or with other methods. It is the responsibility of the Handler to
// manage this concurrency.
+//
+// Users of the slog package should not invoke Handler methods directly.
+// They should use the methods of [Logger] instead.
type Handler interface {
// Enabled reports whether the handler handles records at the given level.
// The handler ignores records whose level is lower.
@@ -47,6 +50,7 @@
//
// Handle methods that produce output should observe the following rules:
// - If r.Time is the zero time, ignore the time.
+ // - If r.PC is zero, ignore it.
// - If an Attr's key is the empty string and the value is not a group,
// ignore the Attr.
// - If a group's key is empty, inline the group's Attrs.
@@ -57,6 +61,7 @@
// WithAttrs returns a new Handler whose attributes consist of
// both the receiver's attributes and the arguments.
// The Handler owns the slice: it may retain, modify or discard it.
+ // [Logger.With] will resolve the Attrs.
WithAttrs(attrs []Attr) Handler
// WithGroup returns a new Handler with the given group appended to
