slog: improve documentation

These changes were all part of the design doc. They make more sense
here.

Change-Id: Ic31954edc1382ab5a1fb805279e4b17245cdc83e
Reviewed-on: https://go-review.googlesource.com/c/exp/+/445336
Reviewed-by: Alan Donovan <adonovan@google.com>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>

slog/handler.go

@@ -27,6 +27,8 @@ import (
 type Handler interface {
 	// Enabled reports whether the handler handles records at the given level.
 	// The handler ignores records whose level is lower.
+	// Enabled is called early, before any arguments are processed,
+	// to save effort if the log event should be discarded.
 	Enabled(Level) bool
 
 	// Handle handles the Record.
@@ -106,6 +108,8 @@ func (h *defaultHandler) WithGroup(name string) Handler {
 type HandlerOptions struct {
 	// Add a "source" attribute to the output whose value is of the form
 	// "file:line".
+	// This is false by default, because there is a cost to extracting this
+	// information.
 	AddSource bool
 
 	// Ignore records with levels below Level.Level().
@@ -119,6 +123,11 @@ type HandlerOptions struct {
 	// The built-in attributes with keys "time", "level", "source", and "msg"
 	// are passed to this function first, except that time and level are omitted
 	// if zero, and source is omitted if AddSourceLine is false.
+	//
+	// ReplaceAttr can be used to change the default keys of the built-in
+	// attributes, convert types (for example, to replace a `time.Time` with the
+	// integer seconds since the Unix epoch), sanitize personal information, or
+	// remove attributes from the output.
 	ReplaceAttr func(a Attr) Attr
 }
 

slog/level.go

@@ -11,7 +11,7 @@ import (
 )
 
 // A Level is the importance or severity of a log event.
-// The higher the level, the less important or severe the event.
+// The higher the level, the more important or severe the event.
 type Level int
 
 // The level numbers below don't really matter too much. Any system can map them

slog/logger.go

@@ -78,8 +78,11 @@ func (l Logger) Handler() Handler { return l.handler }
 func (l Logger) Context() context.Context { return l.ctx }
 
 // 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.
+// Attrs as in [Logger.Log]. The Attrs will be prepended to each output from the
+// Logger.
+//
+// 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

slog/value.go

@@ -344,6 +344,9 @@ const maxLogValues = 100
 
 // Resolve repeatedly calls LogValue on v while it implements LogValuer,
 // and returns the result.
+// If the number of LogValue calls exceeds a threshold, a Value containing an
+// error is returned.
+// Resolve's return value is guaranteed not to be of Kind LogValuerKind.
 func (v Value) Resolve() Value {
 	orig := v
 	for i := 0; i < maxLogValues; i++ {

slog/value_safe.go

@@ -8,7 +8,7 @@ package slog
 
 // This file defines the most portable representation of Value.
 
-// A Value can represent (almost) any Go value, but unlike type any,
+// A Value can represent any Go value, but unlike type any,
 // it can represent most small values without an allocation.
 // The zero Value corresponds to nil.
 type Value struct {

slog/value_unsafe.go

@@ -13,7 +13,7 @@ import (
 	"unsafe"
 )
 
-// A Value can represent (almost) any Go value, but unlike type any,
+// A Value can represent any Go value, but unlike type any,
 // it can represent most small values without an allocation.
 // The zero Value corresponds to nil.
 type Value struct {