Improve docs

Author: nhooyr

README.md

@@ -20,43 +20,37 @@ go get go.coder.com/slog
 - First class [context.Context](https://blog.golang.org/context) support
 - Beautiful logging output by default
 - Multiple adapters
-- First class [\*testing.T](https://godoc.org/go.coder.com/slog/slogtest) support
+- First class [\testing.TB](https://godoc.org/go.coder.com/slog/slogtest) support
 
 ## Example
 
 ```go
-testlog.Info(t, "my message here",
+slogtest.Info(t, "my message here",
     slog.F("field_name", "something or the other"),
-    slog.F("some_map", map[string]interface{}{
-        "nested_fields": "wowow",
-    }),
-    slog.F("some slice", []interface{}{
-        1,
-        "foof",
-        "bar",
-        true,
-    }),
+    slog.F("some_map", slog.Map(
+        slog.F("nested_fields", "wowow"),
+    )),
+    slog.Error(
+        xerrors.Errorf("wrap1: %w",
+            xerrors.Errorf("wrap2: %w",
+                io.EOF),
+        )),
     slog.Component("test"),
-
-    slog.F("name", slog.ValueFunc(func() interface{} {
-        return "wow"
-    })),
 )
 
-// --- PASS: TestExampleTest (0.00s)
-//    test_test.go:38: Sep 06 14:33:52.628 [INFO] (test): my_message_here
+// --- PASS: TestExample (0.00s)
+//    examples_test.go:46: Sep 08 13:54:34.532 [INFO] (test): my_message_here
 //        field_name: something or the other
 //        some_map:
 //          nested_fields: wowow
 //        error:
-//          - msg: wrap2
-//            loc: /Users/nhooyr/src/cdr/slog/test_test.go:43
-//            fun: go.coder.com/slog_test.TestExampleTest
-//          - msg: wrap1
-//            loc: /Users/nhooyr/src/cdr/slog/test_test.go:44
-//            fun: go.coder.com/slog_test.TestExampleTest
+//          - wrap1
+//            go.coder.com/slog_test.TestExample
+//              /Users/nhooyr/src/cdr/slog/examples_test.go:52
+//          - wrap2
+//            go.coder.com/slog_test.TestExample
+//              /Users/nhooyr/src/cdr/slog/examples_test.go:53
 //          - EOF
-//        name: wow
 ```
 
 ## Design justifications

ci/lint.sh

@@ -7,4 +7,4 @@ cd "$(git rev-parse --show-toplevel)"
 # shellcheck disable=SC2046
 shellcheck -x $(git ls-files "*.sh")
 go vet ./...
-#go run golang.org/x/lint/golint -set_exit_status ./...
+go run golang.org/x/lint/golint -set_exit_status ./...

examples_test.go

@@ -1,44 +1,57 @@
 package slog_test
 
 import (
+	"golang.org/x/xerrors"
+	"io"
 	"testing"
 
 	"go.coder.com/slog"
 	"go.coder.com/slog/sloggers/slogtest"
 )
 
-func Example_test() {
+func Example() {
 	// Nil here but would be provided by the testing framework.
-	var t *testing.T
+	var t testing.TB
 
 	slogtest.Info(t, "my message here",
 		slog.F("field_name", "something or the other"),
-		slog.F("some_map", map[string]interface{}{
-			"nested_fields": "wowow",
-		}),
-		slog.F("some slice", []interface{}{
-			1,
-			"foof",
-			"bar",
-			true,
-		}),
+		slog.F("some_map", slog.Map(
+			slog.F("nested_fields", "wowow"),
+		)),
+		slog.Error(
+			xerrors.Errorf("wrap1: %w",
+				xerrors.Errorf("wrap2: %w",
+					io.EOF),
+			)),
 		slog.Component("test"),
-
-		slog.F("name", "hi"),
 	)
 
-	// --- PASS: TestExampleTest (0.00s)
-	//    test_test.go:38: Sep 06 14:33:52.628 [INFO] (test): my_message_here
+	// --- PASS: TestExample (0.00s)
+	//    examples_test.go:46: Sep 08 13:54:34.532 [INFO] (test): my_message_here
 	//        field_name: something or the other
 	//        some_map:
 	//          nested_fields: wowow
 	//        error:
-	//          - msg: wrap2
-	//            loc: /Users/nhooyr/src/cdr/slog/test_test.go:43
-	//            fun: go.coder.com/slog_test.TestExampleTest
-	//          - msg: wrap1
-	//            loc: /Users/nhooyr/src/cdr/slog/test_test.go:44
-	//            fun: go.coder.com/slog_test.TestExampleTest
+	//          - wrap1
+	//            go.coder.com/slog_test.TestExample
+	//              /Users/nhooyr/src/cdr/slog/examples_test.go:52
+	//          - wrap2
+	//            go.coder.com/slog_test.TestExample
+	//              /Users/nhooyr/src/cdr/slog/examples_test.go:53
 	//          - EOF
-	//        name: wow
+}
+
+func TestExample(t *testing.T) {
+	slogtest.Info(t, "my message here",
+		slog.F("field_name", "something or the other"),
+		slog.F("some_map", slog.Map(
+			slog.F("nested_fields", "wowow"),
+		)),
+		slog.Error(
+			xerrors.Errorf("wrap1: %w",
+				xerrors.Errorf("wrap2: %w",
+					io.EOF),
+			)),
+		slog.Component("test"),
+	)
 }

internal/diff/diff.go

@@ -1,3 +1,7 @@
+// Package diff is a helper package around go-cmp for generating
+// diffs between arbitrary interfaces.
+// See https://github.com/google/go-cmp/issues/40#issuecomment-328615283
+// Copied from https://github.com/nhooyr/websocket/blob/1b874731eab56c69c8bb3ebf8a029020c7863fc9/cmp_test.go
 package diff
 
 import (
@@ -6,8 +10,8 @@ import (
 	"github.com/google/go-cmp/cmp"
 )
 
-// https://github.com/google/go-cmp/issues/40#issuecomment-328615283
-// Copied from https://github.com/nhooyr/websocket/blob/1b874731eab56c69c8bb3ebf8a029020c7863fc9/cmp_test.go
+// Diff returns a diff between exp and act.
+// The empty string is returned if they are identical.
 func Diff(exp, act interface{}) string {
 	return cmp.Diff(exp, act, deepAllowUnexported(exp, act))
 }

internal/humanfmt/humanfmt.go

@@ -1,3 +1,5 @@
+// Package humanfmt contains the code to format slog.Entry
+// into a human readable format.
 package humanfmt
 
 import (
@@ -13,6 +15,7 @@ import (
 	"go.coder.com/slog/slogval"
 )
 
+// Entry returns a human readable format for ent.
 func Entry(ent slog.Entry, enableColor bool) string {
 	var ents string
 	if ent.File != "" {

sloggers/sloghuman/sloghuman.go

@@ -1,3 +1,5 @@
+// Package sloghuman contains the slogger
+// that writes logs in a human readable format.
 package sloghuman // import "go.coder.com/slog/sloggers/sloghuman"
 
 import (

sloggers/slogjson/slogjson.go

@@ -1,3 +1,5 @@
+// Package slogjson contains the slogger
+// that writes logs in a JSON format.
 package slogjson // import "go.coder.com/slog/sloggers/slogjson"
 
 import (

sloggers/slogtest/global.go

@@ -1,4 +1,6 @@
-package slogtest
+// Package slogtest contains the slogger for use
+// with Go's testing package.
+package slogtest // import "go.coder.com/slog/sloggers/slogtest"
 
 import (
 	"context"
@@ -17,7 +19,7 @@ type TestOptions struct {
 	IgnoreErrors bool
 }
 
-// Test creates a Logger that writes logs to tb.
+// Test creates a Logger that writes logs to tb in a human readable format.
 func Make(tb testing.TB, opts *TestOptions) slog.Logger {
 	if opts == nil {
 		opts = &TestOptions{}
@@ -28,6 +30,14 @@ func Make(tb testing.TB, opts *TestOptions) slog.Logger {
 	})
 }
 
+// testSink implements slog.Sink but also
+//
+// type testSink interface {
+//	Stdlib() Sink
+//	TestingHelper() func()
+// }
+//
+// See slog.go in root package.
 type testSink struct {
 	tb     testing.TB
 	opts   *TestOptions
@@ -39,12 +49,6 @@ func (ts testSink) Stdlib() slog.Sink {
 	return ts
 }
 
-// Implements:
-// type testSink interface {
-//	Stdlib() Sink
-//	TestingHelper() func()
-// }
-// See slog.go in root package.
 func (ts testSink) TestingHelper() func() {
 	return ts.tb.Helper
 }
@@ -82,3 +86,29 @@ func (ts testSink) LogEntry(ctx context.Context, ent slog.Entry) {
 		ts.tb.Fatal(s)
 	}
 }
+
+var ctx = context.Background()
+
+// Debug logs the given msg and fields to t via t.Log at the debug level.
+func Debug(t testing.TB, msg string, fields ...slog.Field) {
+	t.Helper()
+	Make(t, nil).Debug(ctx, msg, fields...)
+}
+
+// Info logs the given msg and fields to t via t.Log at the info level.
+func Info(t testing.TB, msg string, fields ...slog.Field) {
+	t.Helper()
+	Make(t, nil).Info(ctx, msg, fields...)
+}
+
+// Error logs the given msg and fields to t via t.Error at the error level.
+func Error(t testing.TB, msg string, fields ...slog.Field) {
+	t.Helper()
+	Make(t, nil).Error(ctx, msg, fields...)
+}
+
+// Fatal logs the given msg and fields to t via t.Fatal at the fatal level.
+func Fatal(t testing.TB, msg string, fields ...slog.Field) {
+	t.Helper()
+	Make(t, nil).Fatal(ctx, msg, fields...)
+}