docs: add usage examples for error handling functions and builder pattern in goerr package to enhance documentation clarity

Author: m-mizutani

builder.go

@@ -7,13 +7,24 @@ type Builder struct {
 
 // NewBuilder creates a new Builder.
 // A Builder is useful for creating multiple errors that share a common context, such as a request ID or service name, without repeatedly specifying the same options.
+//
+// Usage:
+//   builder := goerr.NewBuilder(goerr.V("service", "auth"), goerr.V("request_id", "req123"))
+//   err1 := builder.New("user not found")
+//   err2 := builder.Wrap(dbErr, "query failed")
+//   // Both errors will include service and request_id context
 func NewBuilder(options ...Option) *Builder {
 	return &Builder{
 		options: options,
 	}
 }
 
 // With copies the current Builder and adds a new key-value pair.
+//
+// Usage:
+//   baseBuilder := goerr.NewBuilder(goerr.V("service", "auth"))
+//   userBuilder := baseBuilder.With(goerr.V("user_id", "user123"))
+//   err := userBuilder.New("access denied") // includes both service and user_id
 func (x *Builder) With(options ...Option) *Builder {
 	newBuilder := &Builder{
 		options: x.options[:],
@@ -23,13 +34,21 @@ func (x *Builder) With(options ...Option) *Builder {
 }
 
 // New creates a new error with message
+//
+// Usage:
+//   builder := goerr.NewBuilder(goerr.V("service", "auth"))
+//   err := builder.New("authentication failed") // includes service context
 func (x *Builder) New(msg string, options ...Option) *Error {
 	err := newError(append(x.options, options...)...)
 	err.msg = msg
 	return err
 }
 
 // Wrap creates a new Error with caused error and add message.
+//
+// Usage:
+//   builder := goerr.NewBuilder(goerr.V("service", "auth"))
+//   err := builder.Wrap(dbErr, "database query failed") // wraps dbErr with service context
 func (x *Builder) Wrap(cause error, msg string, options ...Option) *Error {
 	err := newError(append(x.options, options...)...)
 	err.msg = msg

error.go

@@ -53,6 +53,12 @@ func New(msg string, options ...Option) *Error {
 }
 
 // Wrap creates a new Error and add message.
+//
+// Usage:
+//   baseErr := fmt.Errorf("connection failed")
+//   err := goerr.Wrap(baseErr, "database operation failed",
+//       goerr.V("host", "localhost"), goerr.V("port", 5432))
+//   // Result: "database operation failed: connection failed" with context
 func Wrap(cause error, msg string, options ...Option) *Error {
 	err := newError(options...)
 	err.msg = msg
@@ -384,6 +390,11 @@ func (x *Error) mergedTags() tags {
 
 // LogValue returns slog.Value for structured logging. It's implementation of slog.LogValuer.
 // https://pkg.go.dev/log/slog#LogValuer
+//
+// Usage:
+//   err := goerr.New("operation failed", goerr.V("user_id", "user123"))
+//   logger.Error("request failed", slog.Any("error", err))
+//   // Automatically outputs structured log with error details, stack trace, and values
 func (x *Error) LogValue() slog.Value {
 	if x == nil {
 		return slog.AnyValue(nil)
@@ -447,6 +458,11 @@ func (x *Error) MarshalJSON() ([]byte, error) {
 //
 // If err is a *goerr.Error, it creates a new *Error that preserves the original stacktrace and adds the new options.
 // If err is a standard error, it wraps the error in a new *goerr.Error with a new stacktrace and adds the options.
+//
+// Usage:
+//   originalErr := goerr.New("validation failed")
+//   enrichedErr := goerr.With(originalErr, goerr.V("user_id", "user123"))
+//   // originalErr is unchanged, enrichedErr has additional context
 func With(err error, options ...Option) *Error {
 	if err == nil {
 		return nil

error_test.go

@@ -803,3 +803,143 @@ func ExampleID() {
 	}
 	// Output: Error is a permission error
 }
+
+// ExampleWith demonstrates how to add context to errors without modifying the original error.
+// goerr.With(err, options...) adds context without modifying the original error
+func ExampleWith() {
+	// Create an original error
+	originalErr := goerr.New("database connection failed")
+
+	// Add context without modifying the original error
+	// Original error remains unchanged, new error with additional context is returned
+	enrichedErr := goerr.With(originalErr,
+		goerr.V("user_id", "user123"),
+		goerr.V("component", "auth-service"),
+	)
+
+	fmt.Println("Original:", originalErr.Error())
+	fmt.Println("Enriched:", enrichedErr.Error())
+
+	// Verify original error has no additional context
+	originalValues := goerr.Values(originalErr)
+	fmt.Printf("Original has %d values\n", len(originalValues))
+
+	// Verify enriched error has the context
+	enrichedValues := goerr.Values(enrichedErr)
+	fmt.Printf("Enriched has %d values\n", len(enrichedValues))
+	fmt.Printf("User ID: %s\n", enrichedValues["user_id"])
+
+	// Output:
+	// Original: database connection failed
+	// Enriched: database connection failed
+	// Original has 0 values
+	// Enriched has 2 values
+	// User ID: user123
+}
+
+// ExampleWrap demonstrates wrapping errors with additional context.
+// goerr.Wrap(cause, message, options...) wraps an existing error and adds additional information
+func ExampleWrap() {
+	// Create a base error
+	baseErr := fmt.Errorf("connection timeout")
+
+	// Wrap the error with additional context
+	wrappedErr := goerr.Wrap(baseErr, "failed to connect to database",
+		goerr.V("host", "localhost"),
+		goerr.V("port", 5432),
+		goerr.V("timeout", "30s"),
+	)
+
+	fmt.Println("Error:", wrappedErr.Error())
+
+	// Access the wrapped values
+	values := goerr.Values(wrappedErr)
+	fmt.Printf("Host: %s\n", values["host"])
+	fmt.Printf("Port: %v\n", values["port"])
+
+	// Check if the original error is preserved
+	if errors.Is(wrappedErr, baseErr) {
+		fmt.Println("Original error is preserved")
+	}
+
+	// Output:
+	// Error: failed to connect to database: connection timeout
+	// Host: localhost
+	// Port: 5432
+	// Original error is preserved
+}
+
+// ExampleBuilder demonstrates using Builder pattern for creating errors with shared context.
+// goerr.NewBuilder(options...) creates a builder, .With(options...) extends it, .New(msg) / .Wrap(err, msg) creates errors
+func ExampleBuilder() {
+	// Create a builder with common context for a request
+	builder := goerr.NewBuilder(
+		goerr.V("service", "user-service"),
+		goerr.V("request_id", "req-12345"),
+	)
+
+	// Create errors using the builder - shared context is automatically included
+	err1 := builder.New("user not found")
+	err2 := builder.Wrap(fmt.Errorf("connection refused"), "database unavailable")
+
+	// All errors created by the builder include the shared context
+	fmt.Println("Error 1:", err1.Error())
+	fmt.Printf("Service: %s\n", goerr.Values(err1)["service"])
+
+	fmt.Println("Error 2:", err2.Error())
+	fmt.Printf("Request ID: %s\n", goerr.Values(err2)["request_id"])
+
+	// Extend the builder with additional context
+	extendedBuilder := builder.With(goerr.V("user_id", "user789"))
+	err3 := extendedBuilder.New("permission denied")
+
+	fmt.Println("Error 3:", err3.Error())
+	fmt.Printf("User ID: %s\n", goerr.Values(err3)["user_id"])
+
+	// Output:
+	// Error 1: user not found
+	// Service: user-service
+	// Error 2: database unavailable: connection refused
+	// Request ID: req-12345
+	// Error 3: permission denied
+	// User ID: user789
+}
+
+// ExampleError_LogValue demonstrates structured logging with slog.LogValuer interface.
+// goerr.Error automatically implements slog.LogValuer for structured logging with slog.Any("error", err)
+func ExampleError_LogValue() {
+	// Create an error with context
+	err := goerr.New("operation failed",
+		goerr.V("user_id", "user123"),
+		goerr.V("operation", "delete_account"),
+	)
+
+	// The error implements slog.LogValuer interface automatically
+	logValue := err.LogValue()
+
+	// Extract some information from the log value for demonstration
+	attrs := logValue.Group()
+	var message, operation string
+	for _, attr := range attrs {
+		switch attr.Key {
+		case "message":
+			message = attr.Value.String()
+		case "values":
+			valueGroup := attr.Value.Group()
+			for _, valueAttr := range valueGroup {
+				if valueAttr.Key == "operation" {
+					operation = valueAttr.Value.String()
+				}
+			}
+		}
+	}
+
+	fmt.Printf("Message: %s\n", message)
+	fmt.Printf("Operation: %s\n", operation)
+	fmt.Println("Structured logging ready")
+
+	// Output:
+	// Message: operation failed
+	// Operation: delete_account
+	// Structured logging ready
+}