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
