Improve docs and add more examples

Author: nhooyr

example_marshaller_test.go

@@ -0,0 +1,34 @@
+package slog_test
+
+import (
+	"context"
+	"os"
+
+	"cdr.dev/slog"
+	"cdr.dev/slog/sloggers/sloghuman"
+)
+
+type myStruct struct {
+	foo int
+	bar int
+}
+
+func (s myStruct) MarshalJSON() ([]byte, error) {
+	return slog.M(
+		slog.F("foo", s.foo),
+		slog.F("bar", s.foo),
+	).MarshalJSON()
+}
+
+func Example_marshaller() {
+	l := sloghuman.Make(os.Stdout)
+
+	l.Info(context.Background(), "wow",
+		slog.F("myStruct", myStruct{
+			foo: 1,
+			bar: 2,
+		}),
+	)
+
+	// 2019-12-16 17:31:37.120 [INFO]	<example_marshaller_test.go:26>	wow	{"myStruct": {"foo": 1, "bar": 1}}
+}

example_test.go

@@ -44,6 +44,26 @@ func Example() {
 	//    - EOF
 }
 
+func Example_struct() {
+	l := sloghuman.Make(os.Stdout)
+
+	type hello struct {
+		Meow int       `json:"meow"`
+		Bar  string    `json:"bar"`
+		M    time.Time `json:"m"`
+	}
+
+	l.Info(context.Background(), "check out my structure",
+		slog.F("hello", hello{
+			Meow: 1,
+			Bar:  "barbar",
+			M:    time.Date(2000, time.February, 5, 4, 4, 4, 0, time.UTC),
+		}),
+	)
+
+	// 2019-12-16 17:31:51.769 [INFO]	<example_test.go:56>	check out my structure	{"hello": {"meow": 1, "bar": "barbar", "m": "2000-02-05T04:04:04Z"}}
+}
+
 func Example_testing() {
 	// Provided by the testing package in tests.
 	var t testing.TB
@@ -66,17 +86,16 @@ func Example_tracing() {
 }
 
 func Example_multiple() {
-	ctx := context.Background()
 	l := sloghuman.Make(os.Stdout)
 
 	f, err := os.OpenFile("stackdriver", os.O_WRONLY|os.O_APPEND|os.O_CREATE, 0644)
 	if err != nil {
-		l.Fatal(ctx, "failed to open stackdriver log file", slog.Error(err))
+		l.Fatal(context.Background(), "failed to open stackdriver log file", slog.Error(err))
 	}
 
 	l = slog.Make(l, slogstackdriver.Make(f))
 
-	l.Info(ctx, "log to stdout and stackdriver")
+	l.Info(context.Background(), "log to stdout and stackdriver")
 
 	// 2019-12-07 20:59:55.790 [INFO]	<example_test.go:46>	log to stdout and stackdriver
 }

map.go

@@ -32,8 +32,7 @@ var _ json.Marshaler = Map(nil)
 //
 // 5. slices and arrays go through the encode function for every element.
 //
-// 6. If the value cannot be encoded directly with json.Marshal (like channels)
-//    then fmt.Sprintf("%+v") is used.
+// 6. For values that cannot be encoded with json.Marshal, fmt.Sprintf("%+v") is used.
 //
 // 7. json.Marshal(v) is used for all other values.
 func (m Map) MarshalJSON() ([]byte, error) {

map_test.go

@@ -93,7 +93,7 @@ func TestMap(t *testing.T) {
 					{
 						"msg": "failed to marshal to JSON",
 						"fun": "cdr.dev/slog.encodeJSON",
-						"loc": "`+mapTestFile+`:132"
+						"loc": "`+mapTestFile+`:131"
 					},
 					"json: error calling MarshalJSON for type slog_test.complexJSON: json: unsupported type: complex128"
 				],