Addresses issue #2745 by providing complete documentation for the ContextTimeout
middleware, which was previously undocumented despite being the recommended
approach over the deprecated Timeout middleware.
**Documentation Added:**
**Overview & Key Differences:**
- Clear explanation of why ContextTimeout is preferred over Timeout middleware
- Highlights safety improvements (no response writer interference, no data races)
- Explains cooperative cancellation model
**Configuration Examples:**
- Basic usage with simple timeout
- Custom error handling for timeout responses
- Route-specific skipping with Skipper
- Advanced configuration patterns
**Handler Examples (3 detailed scenarios):**
- Context-aware database queries with proper error handling
- Long-running operations using goroutines and select statements
- HTTP client requests with context propagation
**Best Practices & Common Patterns:**
- Database operations: `db.QueryContext(ctx, ...)`
- HTTP requests: `http.NewRequestWithContext(ctx, ...)`
- Redis operations: `client.Get(ctx, key)`
- CPU-intensive loops with context checking
**Enhanced Field Documentation:**
- Detailed explanations for Skipper, ErrorHandler, and Timeout fields
- Examples for each configuration option
- Recommended timeout values for different use cases
**Function Documentation:**
- Comprehensive ContextTimeout() documentation with usage examples
- Enhanced ContextTimeoutWithConfig() with advanced patterns
- ToMiddleware() method documentation for validation scenarios
This resolves user confusion about which timeout middleware to use and
provides practical examples showing how handlers should be implemented
to work effectively with context-based timeouts.
Fixes#2745🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
