slog-handler-guide: minor prose tweaks Change-Id: Ie5299ec0f6e9d1936281152290edf397a0956b90 Reviewed-on: https://go-review.googlesource.com/c/example/+/514055 Run-TryBot: Jonathan Amsterdam <jba@google.com> Reviewed-by: Ian Cottrell <iancottrell@google.com> TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/slog-handler-guide/README.md b/slog-handler-guide/README.md index 3172f0e..946f653 100644 --- a/slog-handler-guide/README.md +++ b/slog-handler-guide/README.md
@@ -44,7 +44,7 @@ and the output methods. An output method fulfills the main role of a logger: producing log output. -Here is an example call to an output method: +Here is a call to an output method: logger.Info("hello", "key", value) @@ -69,7 +69,6 @@ The `WithGroup` method is used to avoid avoid key collisions in large programs by establishing separate namespaces. - This call creates a new `Logger` value with a group named "g": logger = logger.WithGroup("g") @@ -140,8 +139,8 @@ We'll support only one option, the ability to set a minimum level in order to supress detailed log output. -Handlers should always use the `slog.Leveler` type for this option. -`Leveler` is implemented by both `Level` and `LevelVar`. +Handlers should always declare this option to be a `slog.Leveler`. +The `slog.Leveler` interface is implemented by both `Level` and `LevelVar`. A `Level` value is easy for the user to provide, but changing the level of multiple handlers requires tracking them all. If the user instead passes a `LevelVar`, then a single change to that `LevelVar` @@ -220,7 +219,7 @@ 5. Output the buffer. -That is how our `IndentHandler`'s `Handle` method is structured: +That is how `IndentHandler.Handle` is structured: ``` func (h *IndentHandler) Handle(ctx context.Context, r slog.Record) error { @@ -554,7 +553,7 @@ // ... } -A single handleWidgets request might generate hundreds of log lines. +A single `handleWidgets` request might generate hundreds of log lines. For instance, it might contain code like this: for _, w := range widgets { @@ -728,7 +727,7 @@ } ``` -Calling `TestHandler` is easy. The hard part is parsing the output. +Calling `TestHandler` is easy. The hard part is parsing your handler's output. `TestHandler` calls your handler multiple times, resulting in a sequence of log entries. It is your job to parse each entry into a `map[string]any`. @@ -851,8 +850,7 @@ The built-in handlers do not follow that advice. Few things are more frustrating than being unable to debug a problem that causes logging to fail; -our feeling is that it is -better to produce some output, however imperfect, than to produce none at all. +it is better to produce some output, however imperfect, than to produce none at all. That is why methods like `Logger.Info` convert programming bugs in their list of key-value pairs, like missing values or malformed keys, into `Attr`s that contain as much information as possible. @@ -878,7 +876,7 @@ a new `Kind`—a backwards-compatible change under the Go 1 Compatibility Promise—and the handler wasn't updated. That is certainly a problem, but it shouldn't deprive -readers of the logs from seeing the rest of the output. +readers from seeing the rest of the log output. There is one circumstance where returning an error from `Handler.Handle` is appropriate. If the output operation itself fails, the best course of action is to report
diff --git a/slog-handler-guide/guide.md b/slog-handler-guide/guide.md index 92bcd26..969415f 100644 --- a/slog-handler-guide/guide.md +++ b/slog-handler-guide/guide.md
@@ -31,7 +31,7 @@ and the output methods. An output method fulfills the main role of a logger: producing log output. -Here is an example call to an output method: +Here is a call to an output method: logger.Info("hello", "key", value) @@ -56,7 +56,6 @@ The `WithGroup` method is used to avoid avoid key collisions in large programs by establishing separate namespaces. - This call creates a new `Logger` value with a group named "g": logger = logger.WithGroup("g") @@ -102,8 +101,8 @@ We'll support only one option, the ability to set a minimum level in order to supress detailed log output. -Handlers should always use the `slog.Leveler` type for this option. -`Leveler` is implemented by both `Level` and `LevelVar`. +Handlers should always declare this option to be a `slog.Leveler`. +The `slog.Leveler` interface is implemented by both `Level` and `LevelVar`. A `Level` value is easy for the user to provide, but changing the level of multiple handlers requires tracking them all. If the user instead passes a `LevelVar`, then a single change to that `LevelVar` @@ -178,7 +177,7 @@ 5. Output the buffer. -That is how our `IndentHandler`'s `Handle` method is structured: +That is how `IndentHandler.Handle` is structured: %include indenthandler1/indent_handler.go handle - @@ -373,7 +372,7 @@ // ... } -A single handleWidgets request might generate hundreds of log lines. +A single `handleWidgets` request might generate hundreds of log lines. For instance, it might contain code like this: for _, w := range widgets { @@ -460,7 +459,7 @@ %include indenthandler3/indent_handler_test.go TestSlogtest - -Calling `TestHandler` is easy. The hard part is parsing the output. +Calling `TestHandler` is easy. The hard part is parsing your handler's output. `TestHandler` calls your handler multiple times, resulting in a sequence of log entries. It is your job to parse each entry into a `map[string]any`. @@ -569,8 +568,7 @@ The built-in handlers do not follow that advice. Few things are more frustrating than being unable to debug a problem that causes logging to fail; -our feeling is that it is -better to produce some output, however imperfect, than to produce none at all. +it is better to produce some output, however imperfect, than to produce none at all. That is why methods like `Logger.Info` convert programming bugs in their list of key-value pairs, like missing values or malformed keys, into `Attr`s that contain as much information as possible. @@ -596,7 +594,7 @@ a new `Kind`—a backwards-compatible change under the Go 1 Compatibility Promise—and the handler wasn't updated. That is certainly a problem, but it shouldn't deprive -readers of the logs from seeing the rest of the output. +readers from seeing the rest of the log output. There is one circumstance where returning an error from `Handler.Handle` is appropriate. If the output operation itself fails, the best course of action is to report