log/slog: clarify the limits of TextHandler output parseability

Give an example illustrating the problem with dots inside groups
or keys. Clarify that to fix it in general, you need to do more
than escape the keys, since that won't distinguish the group "a.b"
from the two groups "a" and "b".

Updates #56345.

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

diff --git a/src/log/slog/text_handler.go b/src/log/slog/text_handler.go
index 307d5c9d75c56cb3ddbfa5ac7b86575842c14220..739c662f85a3c0b035fe7525e5fccbad99c855f3 100644 (file)
--- a/src/log/slog/text_handler.go
+++ b/src/log/slog/text_handler.go
@@ -68,7 +68,7 @@ func (h *TextHandler) WithGroup(name string) Handler {
 // If the AddSource option is set and source information is available,
 // the key is "source" and the value is output as FILE:LINE.
 //
-// The message's key "msg".
+// The message's key is "msg".
 //
 // To modify these or other attributes, or remove them from the output, use
 // [HandlerOptions.ReplaceAttr].
@@ -80,9 +80,13 @@ func (h *TextHandler) WithGroup(name string) Handler {
 // characters, non-printing characters, '"' or '='.
 //
 // Keys inside groups consist of components (keys or group names) separated by
-// dots. No further escaping is performed. If it is necessary to reconstruct the
-// group structure of a key even in the presence of dots inside components, use
-// [HandlerOptions.ReplaceAttr] to escape the keys.
+// dots. No further escaping is performed.
+// Thus there is no way to determine from the key "a.b.c" whether there
+// are two groups "a" and "b" and a key "c", or a single group "a.b" and a key "c",
+// or single group "a" and a key "b.c".
+// If it is necessary to reconstruct the group structure of a key
+// even in the presence of dots inside components, use
+// [HandlerOptions.ReplaceAttr] to encode that information in the key.
 //
 // Each call to Handle results in a single serialized call to
 // io.Writer.Write.