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 golang#56345.

Change-Id: Ide301899c548d50b0a1f18e93e93d6e11ad485cf
Reviewed-on: https://go-review.googlesource.com/c/go/+/478199
Reviewed-by: Alan Donovan <[email protected]>
Run-TryBot: Jonathan Amsterdam <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>

Author: jba

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.