docs: clarify and expand documentation across core subsystems

- Improve and clarify documentation for errors, options, logger, metric, ring buffer, and thread management throughout the codebase
- Expand comments to explain default behaviors, thread safety, and usage examples for queue configuration and job options
- Add detailed descriptions of buffer resizing, shutdown, and task handling logic in the ring buffer implementation
- Enhance logger and metric interfaces with usage guidance and method explanations
- Document thread management utilities for goroutine lifecycle control

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>

Author: appleboy

errors.go

@@ -3,10 +3,20 @@ package queue
 import "errors"
 
 var (
-	// ErrNoTaskInQueue there is nothing in the queue
+	// ErrNoTaskInQueue is returned by Worker.Request() when the queue is currently empty.
+	// This is a temporary condition - new tasks may be added later.
+	// The queue scheduler uses this error to determine when to retry or wait for notifications.
 	ErrNoTaskInQueue = errors.New("golang-queue: no task in queue")
-	// ErrQueueHasBeenClosed the current queue is closed
+
+	// ErrQueueHasBeenClosed is returned by Worker.Request() during/after shutdown when no tasks remain.
+	// This is a terminal state indicating the queue has been shut down and drained.
+	// Once this error appears, no new tasks will be processed.
+	// Triggered by: calling Shutdown() or Release() on the queue.
 	ErrQueueHasBeenClosed = errors.New("golang-queue: queue has been closed")
-	// ErrMaxCapacity Maximum size limit reached
+
+	// ErrMaxCapacity is returned by Queue() or QueueTask() when the queue is at maximum capacity.
+	// This only occurs when WithQueueSize() is used to set a capacity limit.
+	// To handle: retry later, drop the task, or process it synchronously.
+	// Triggered by: attempting to enqueue when count >= capacity.
 	ErrMaxCapacity = errors.New("golang-queue: maximum size limit reached")
 )

job/option.go

@@ -2,19 +2,27 @@ package job
 
 import "time"
 
-// Options is a set of options for the queue
+// Options configures retry behavior and timeouts for individual jobs.
+// These settings control how failed tasks are retried and when they time out.
 type Options struct {
-	retryCount  int64
-	retryDelay  time.Duration
-	retryFactor float64
-	retryMin    time.Duration
-	retryMax    time.Duration
-	jitter      bool
-
-	timeout time.Duration
+	retryCount  int64         // Maximum number of retry attempts (0 means no retries)
+	retryDelay  time.Duration // Fixed delay between retries (0 uses exponential backoff)
+	retryFactor float64       // Exponential backoff multiplier (default: 2)
+	retryMin    time.Duration // Minimum backoff delay (default: 100ms)
+	retryMax    time.Duration // Maximum backoff delay (default: 10s)
+	jitter      bool          // Add randomization to backoff to prevent thundering herd (default: false)
+
+	timeout time.Duration // Maximum time allowed for job execution (default: 60 minutes)
 }
 
-// newDefaultOptions create new default options
+// newDefaultOptions creates job options with sensible defaults:
+//   - retryCount: 0 (no automatic retries)
+//   - retryDelay: 0 (uses exponential backoff when retries are enabled)
+//   - retryFactor: 2 (doubles the delay between each retry)
+//   - retryMin: 100ms (minimum backoff delay)
+//   - retryMax: 10s (maximum backoff delay)
+//   - timeout: 60 minutes (job execution timeout)
+//   - jitter: false (no randomization in backoff)
 func newDefaultOptions() Options {
 	return Options{
 		retryCount:  0,
@@ -27,18 +35,38 @@ func newDefaultOptions() Options {
 	}
 }
 
-// AllowOption is a function that sets some option on the Options
+// AllowOption provides optional configuration for individual job execution.
+// All fields are pointers to distinguish between "not set" and "set to zero value".
+// This allows partial configuration while keeping unspecified fields at their defaults.
+//
+// Example usage:
+//
+//	opts := AllowOption{
+//	    RetryCount: job.Int64(3),        // Retry failed jobs up to 3 times
+//	    Timeout:    job.Time(5 * time.Minute), // 5 minute timeout
+//	}
+//	q.QueueTask(myTask, opts)
 type AllowOption struct {
-	RetryCount  *int64
-	RetryDelay  *time.Duration
-	RetryFactor *float64
-	RetryMin    *time.Duration
-	RetryMax    *time.Duration
-	Jitter      *bool
-	Timeout     *time.Duration
+	RetryCount  *int64         // Maximum retry attempts (nil uses default: 0)
+	RetryDelay  *time.Duration // Fixed delay between retries (nil uses exponential backoff)
+	RetryFactor *float64       // Backoff multiplier (nil uses default: 2)
+	RetryMin    *time.Duration // Minimum backoff delay (nil uses default: 100ms)
+	RetryMax    *time.Duration // Maximum backoff delay (nil uses default: 10s)
+	Jitter      *bool          // Enable backoff jitter (nil uses default: false)
+	Timeout     *time.Duration // Job execution timeout (nil uses default: 60 minutes)
 }
 
-// NewOptions create new options
+// NewOptions creates a job Options struct by merging defaults with provided AllowOption values.
+// Only non-nil fields in AllowOption will override the defaults.
+// This allows partial configuration where unspecified options retain their default values.
+//
+// Example:
+//
+//	// Only override retry count and timeout, keep other defaults
+//	opts := job.NewOptions(job.AllowOption{
+//	    RetryCount: job.Int64(5),
+//	    Timeout:    job.Time(10 * time.Minute),
+//	})
 func NewOptions(opts ...AllowOption) Options {
 	o := newDefaultOptions()
 
@@ -75,22 +103,45 @@ func NewOptions(opts ...AllowOption) Options {
 	return o
 }
 
-// Int64 is a helper routine that allocates a new int64 value
+// Int64 is a helper function that creates a pointer to an int64 value.
+// Useful for setting AllowOption fields that require *int64.
+//
+// Example:
+//
+//	opts := AllowOption{RetryCount: job.Int64(3)}
 func Int64(val int64) *int64 {
 	return &val
 }
 
-// Float64 is a helper routine that allocates a new float64 value
+// Float64 is a helper function that creates a pointer to a float64 value.
+// Useful for setting AllowOption fields that require *float64.
+//
+// Example:
+//
+//	opts := AllowOption{RetryFactor: job.Float64(1.5)}
 func Float64(val float64) *float64 {
 	return &val
 }
 
-// Time is a helper routine that allocates a new time value
+// Time is a helper function that creates a pointer to a time.Duration value.
+// Useful for setting AllowOption fields that require *time.Duration.
+//
+// Example:
+//
+//	opts := AllowOption{
+//	    Timeout:    job.Time(5 * time.Minute),
+//	    RetryDelay: job.Time(2 * time.Second),
+//	}
 func Time(v time.Duration) *time.Duration {
 	return &v
 }
 
-// Bool is a helper routine that allocates a new bool value
+// Bool is a helper function that creates a pointer to a bool value.
+// Useful for setting AllowOption fields that require *bool.
+//
+// Example:
+//
+//	opts := AllowOption{Jitter: job.Bool(true)}
 func Bool(val bool) *bool {
 	return &val
 }

logger.go

@@ -6,17 +6,47 @@ import (
 	"os"
 )
 
-// Logger interface is used throughout gorush
+// Logger defines the interface for logging queue events, errors, and fatal conditions.
+// The queue uses this interface to report:
+//   - Info: Normal operations (shutdown, retry attempts)
+//   - Error: Recoverable errors (task failures, runtime errors)
+//   - Fatal: Panics and critical failures (includes stack traces)
+//
+// Implement this interface to integrate with custom logging systems (logrus, zap, etc.).
 type Logger interface {
+	// Infof logs formatted informational messages.
 	Infof(format string, args ...any)
+
+	// Errorf logs formatted error messages.
 	Errorf(format string, args ...any)
+
+	// Fatalf logs formatted fatal errors with stack trace information.
+	// Used for panics and critical failures.
 	Fatalf(format string, args ...any)
+
+	// Info logs informational messages.
 	Info(args ...any)
+
+	// Error logs error messages.
 	Error(args ...any)
+
+	// Fatal logs fatal errors with stack trace information.
+	// Used for panics and critical failures.
 	Fatal(args ...any)
 }
 
-// NewLogger for simple logger.
+// NewLogger creates a standard logger that writes to stderr with timestamps.
+// This is the default logger used by queues unless overridden with WithLogger.
+//
+// Log format:
+//   - INFO messages: Simple timestamped output
+//   - ERROR messages: Simple timestamped output
+//   - FATAL messages: Includes stack trace with file:line information
+//
+// Use cases:
+//   - Development and debugging
+//   - Simple production deployments without structured logging
+//   - When detailed error context is needed
 func NewLogger() Logger {
 	return defaultLogger{
 		infoLogger:  log.New(os.Stderr, "INFO: ", log.Ldate|log.Ltime),
@@ -25,20 +55,28 @@ func NewLogger() Logger {
 	}
 }
 
+// defaultLogger is the standard logger implementation using Go's log package.
+// It provides timestamped output to stderr and includes stack traces for fatal errors.
 type defaultLogger struct {
-	infoLogger  *log.Logger
-	errorLogger *log.Logger
-	fatalLogger *log.Logger
+	infoLogger  *log.Logger // Logger for informational messages
+	errorLogger *log.Logger // Logger for error messages
+	fatalLogger *log.Logger // Logger for fatal errors with stack traces
 }
 
+// logWithCallerf logs a formatted message with stack trace information.
+// The stack trace helps identify where the fatal error occurred.
+// Skip depth of 3: logWithCallerf -> Fatalf -> user code
 func (l defaultLogger) logWithCallerf(logger *log.Logger, format string, args ...any) {
-	stackInfo := stack(3) // Assuming stack(3) returns caller info string
-	// Prepend stack info to the arguments and adjust the format string
+	stackInfo := stack(3) // Get caller info (file:line)
+	// Prepend stack info to the log message
 	logger.Printf("%s "+format, append([]any{stackInfo}, args...)...)
 }
 
+// logWithCaller logs unformatted arguments with stack trace information.
+// The stack trace helps identify where the fatal error occurred.
+// Skip depth of 3: logWithCaller -> Fatal -> user code
 func (l defaultLogger) logWithCaller(logger *log.Logger, args ...any) {
-	stack := stack(3)
+	stack := stack(3) // Get caller info (file:line)
 	logger.Println(append([]any{stack}, args...)...)
 }
 
@@ -66,12 +104,21 @@ func (l defaultLogger) Fatal(args ...any) {
 	l.logWithCaller(l.fatalLogger, args...)
 }
 
-// NewEmptyLogger for simple logger.
+// NewEmptyLogger creates a no-op logger that discards all log messages.
+// This is useful for:
+//   - Performance-sensitive production environments where logging overhead matters
+//   - Testing scenarios where log output would clutter test results
+//   - Silent background workers that don't need observability
+//
+// Example:
+//
+//	q := queue.NewPool(5, queue.WithLogger(queue.NewEmptyLogger()))
 func NewEmptyLogger() Logger {
 	return emptyLogger{}
 }
 
-// EmptyLogger no meesgae logger
+// emptyLogger is a no-op implementation that discards all log messages.
+// All methods are implemented as empty functions with no side effects.
 type emptyLogger struct{}
 
 func (l emptyLogger) Infof(format string, args ...any)  {}