Update docs (#13)

* docs: Prefer handler over package-level functions

* chore: update examples

* docs: Remove plug for bugsnag

The maturity of the two packages are now more equal than before

* docs: Improve writing in the README

Author: kinbiko

README.md

@@ -7,34 +7,36 @@
 [![Go Documentation](http://img.shields.io/badge/godoc-documentation-blue.svg?style=flat)](https://pkg.go.dev/github.com/kinbiko/rogerr?tab=doc)
 [![License](https://img.shields.io/github/license/kinbiko/rogerr.svg?style=flat)](https://github.com/kinbiko/rogerr/blob/master/LICENSE)
 
-Consistent and greppable errors makes your logger and error reporting tools happy. This zero-dependency error handling support package for Go helps you achieve just that.
+A Go package for error handling with structured metadata. Zero dependencies.
 
-[Blog post explaining the problem and the solution in detail](https://kinbiko.com/posts/2022-07-30-error-messages-should-be-boring/).
+[Blog post with detailed explanation](https://kinbiko.com/posts/2022-07-30-error-messages-should-be-boring/).
 
-## Usage
+## Problem
 
-When creating errors, **do not include goroutine-specific or request-specific information as part of the error message itself**.
-Error messages with these specific bits of information often break filtering/grouping algorithms, e.g. as used by error reporting tools like Sentry/Rollbar/etc. (If you use Bugsnag, I recommend [kinbiko/bugsnag](https://github.com/kinbiko/bugsnag) for an **even better** experience than this package).
+Error messages that include unique data (user IDs, timestamps, etc.) break error grouping in monitoring tools like Sentry and Rollbar.
 
-Instead this information should be treated as structured data, akin to structured logging solutions like Logrus and Zap.
-In Go, it's conventional to attach this kind of request specific 'diagnostic' metadata to a `context.Context` type, and that's what this package enables too.
+## Solution
 
-At a high level:
+Store unique data as structured metadata separate from the error message.
+This package attaches metadata to Go's `context.Context` and preserves it when wrapping errors.
 
-1. Attach metadata to your context with `rogerr.WithMetadata` or `rogerr.WithMetadatum`.
-1. When you come across an error, use `err = rogerr.Wrap(ctx, err, msg)` to attach the metadata accumulated so far to the wrapped error.
-1. Return the error as you would normally, and at the time of logging/reporting, extract the metadata with `md := rogerr.Metadata(err)`.
-1. Record the _structured_ metadata alongside the error message.
+## Usage
 
-For more details, see [the official docs](https://pkg.go.dev/github.com/kinbiko/rogerr).
+1. Create an ErrorHandler: `handler := rogerr.NewErrorHandler()`
+2. Add metadata to context: `ctx = rogerr.WithMetadatum(ctx, "userID", 123)`
+3. Wrap errors with metadata: `err = handler.Wrap(ctx, err, "operation failed")`
+4. Extract metadata for logging: `metadata := rogerr.Metadata(err)`
 
-### Build Recommendations
+### Build Options
 
-For cleaner stacktrace file paths, build with the `-trimpath` flag:
+For cleaner stacktraces, use the `-trimpath` flag:
 
 ```bash
 go build -trimpath ./cmd/myapp
 ```
 
-This removes local build path prefixes, showing module-relative paths instead of absolute machine-specific paths.
-Not needed if stacktraces are disabled with `WithStacktrace(false)`, e.g. for performance reasons.
+This shows module-relative paths instead of absolute paths.
+Skip this if you disable stacktraces with `rogerr.WithStacktrace(false)`.
+
+[Full documentation](https://pkg.go.dev/github.com/kinbiko/rogerr)
+

doc.go

@@ -1,4 +1,5 @@
-/*Package rogerr is a zero-dependency error handling support package.
+/*
+Package rogerr is a zero-dependency error handling support package.
 
 When creating errors, **do not include goroutine-specific or request-specific information as part of the error message itself**.
 Error messages with these specific bits of information often break filtering/grouping algorithms, e.g. as used by error reporting tools like Sentry/Rollbar/etc. (If you use Bugsnag, I recommend [kinbiko/bugsnag](https://github.com/kinbiko/bugsnag) for an **even better** experience than this package).
@@ -8,8 +9,9 @@ In Go, it's conventional to attach this kind of request specific 'diagnostic' me
 
 At a high level:
 
+1. Create an ErrorHandler with `handler := rogerr.NewErrorHandler()`.
 1. Attach metadata to your context with `rogerr.WithMetadata` or `rogerr.WithMetadatum`.
-1. When you come across an error, use `err = rogerr.Wrap(ctx, err, msg)` to attach the metadata accumulated so far to the wrapped error.
+1. When you come across an error, use `err = handler.Wrap(ctx, err, msg)` to attach the metadata accumulated so far to the wrapped error.
 1. Return the error as you would normally, and at the time of logging/reporting, extract the metadata with `md := rogerr.Metadata(err)`.
 1. Record the _structured_ metadata alongside the error message.
 */

example_test.go

@@ -8,6 +8,8 @@ import (
 )
 
 func ExampleWrap() {
+	handler := rogerr.NewErrorHandler()
+
 	someFuncWithAProblem := func(_ context.Context) error {
 		return fmt.Errorf("some low level err")
 	}
@@ -18,7 +20,7 @@ func ExampleWrap() {
 
 		err := someFuncWithAProblem(ctx)
 		if err != nil {
-			return rogerr.Wrap(ctx, err, "wrap args")
+			return handler.Wrap(ctx, err, "wrap args")
 		}
 		return nil
 	}