log/slog: rearrange package doc

Move the "Attrs and Values" section lower. It describes an optimization;
the API it covers is not essential.

Also, move the brief section on Logger.With up to the first section.
It was in the "Groups" section but didn't belong there.

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

diff --git a/src/log/slog/doc.go b/src/log/slog/doc.go
index 57f83bb52dc4195a2383ef34b49cfdfe4873e321..3b242591fc789aa462f3ad1de5feb175e6ac4974 100644 (file)
--- a/src/log/slog/doc.go
+++ b/src/log/slog/doc.go
@@ -78,38 +78,6 @@ will cause the top-level functions like [Info] to use it.
 so that existing applications that use [log.Printf] and related functions
 will send log records to the logger's handler without needing to be rewritten.
 
-# Attrs and Values
-
-An [Attr] is a key-value pair. The Logger output methods accept Attrs as well as
-alternating keys and values. The statement
-
-       slog.Info("hello", slog.Int("count", 3))
-
-behaves the same as
-
-       slog.Info("hello", "count", 3)
-
-There are convenience constructors for [Attr] such as [Int], [String], and [Bool]
-for common types, as well as the function [Any] for constructing Attrs of any
-type.
-
-The value part of an Attr is a type called [Value].
-Like an [any], a Value can hold any Go value,
-but it can represent typical values, including all numbers and strings,
-without an allocation.
-
-For the most efficient log output, use [Logger.LogAttrs].
-It is similar to [Logger.Log] but accepts only Attrs, not alternating
-keys and values; this allows it, too, to avoid allocation.
-
-The call
-
-       logger.LogAttrs(nil, slog.LevelInfo, "hello", slog.Int("count", 3))
-
-is the most efficient way to achieve the same output as
-
-       slog.Info("hello", "count", 3)
-
 Some attributes are common to many log calls.
 For example, you may wish to include the URL or trace identifier of a server request
 with all log events arising from the request.
@@ -164,7 +132,7 @@ How this qualification is displayed depends on the handler.
 [TextHandler] separates the group and attribute names with a dot.
 [JSONHandler] treats each group as a separate JSON object, with the group name as the key.
 
-Use [Group] to create a Group Attr from a name and a list of key-value pairs:
+Use [Group] to create a Group attribute from a name and a list of key-value pairs:
 
        slog.Group("request",
            "method", r.Method,
@@ -212,6 +180,38 @@ in "Ctx" do. For example,
 
 It is recommended to pass a context to an output method if one is available.
 
+# Attrs and Values
+
+An [Attr] is a key-value pair. The Logger output methods accept Attrs as well as
+alternating keys and values. The statement
+
+       slog.Info("hello", slog.Int("count", 3))
+
+behaves the same as
+
+       slog.Info("hello", "count", 3)
+
+There are convenience constructors for [Attr] such as [Int], [String], and [Bool]
+for common types, as well as the function [Any] for constructing Attrs of any
+type.
+
+The value part of an Attr is a type called [Value].
+Like an [any], a Value can hold any Go value,
+but it can represent typical values, including all numbers and strings,
+without an allocation.
+
+For the most efficient log output, use [Logger.LogAttrs].
+It is similar to [Logger.Log] but accepts only Attrs, not alternating
+keys and values; this allows it, too, to avoid allocation.
+
+The call
+
+       logger.LogAttrs(nil, slog.LevelInfo, "hello", slog.Int("count", 3))
+
+is the most efficient way to achieve the same output as
+
+       slog.Info("hello", "count", 3)
+
 # Customizing a type's logging behavior
 
 If a type implements the [LogValuer] interface, the [Value] returned from its LogValue