docs: improve codebase documentation and comments

- Add detailed comments explaining the `Fn` type and its usage in Gin HTTP requests.
- Update the `Skipper` comment to clarify its purpose and functionality.
- Improve comments for the `config` struct fields to provide clearer descriptions.
- Enhance the comment for the `SetLogger` function to include detailed information about its configuration and logging behavior.
- Add comprehensive comments for the `ParseLevel` function, detailing its parameters and return values.
- Update the `Get` function comment to explain its purpose and usage in retrieving a logger from the Gin context.

Signed-off-by: appleboy <[email protected]>

logger.go

@@ -12,39 +12,69 @@ import (
 	"github.com/rs/zerolog"
 )
 
+// Fn is a function type that takes a gin.Context and a zerolog.Logger as parameters,
+// and returns a zerolog.Logger. It is typically used to modify or enhance the logger
+// within the context of a Gin HTTP request.
 type Fn func(*gin.Context, zerolog.Logger) zerolog.Logger
 
-// Skipper is a function to skip logs based on provided Context
+// Skipper defines a function to skip middleware. It takes a gin.Context as input
+// and returns a boolean indicating whether to skip the middleware for the given context.
 type Skipper func(c *gin.Context) bool
 
-// Config defines the config for logger middleware
+// config holds the configuration for the logger middleware.
 type config struct {
+	// logger is a function that defines the logging behavior.
 	logger Fn
-	// UTC a boolean stating whether to use UTC time zone or local.
-	utc             bool
-	skipPath        []string
+	// utc is a boolean stating whether to use UTC time zone or local.
+	utc bool
+	// skipPath is a list of paths to be skipped from logging.
+	skipPath []string
+	// skipPathRegexps is a list of regular expressions to match paths to be skipped from logging.
 	skipPathRegexps []*regexp.Regexp
-	// skip is a Skipper that indicates which logs should not be written.
-	// Optional.
+	// skip is a Skipper that indicates which logs should not be written. Optional.
 	skip Skipper
-	// Output is a writer where logs are written.
-	// Optional. Default value is gin.DefaultWriter.
+	// output is a writer where logs are written. Optional. Default value is gin.DefaultWriter.
 	output io.Writer
-	// the log level used for request with status code < 400
+	// defaultLevel is the log level used for requests with status code < 400.
 	defaultLevel zerolog.Level
-	// the log level used for request with status code between 400 and 499
+	// clientErrorLevel is the log level used for requests with status code between 400 and 499.
 	clientErrorLevel zerolog.Level
-	// the log level used for request with status code >= 500
+	// serverErrorLevel is the log level used for requests with status code >= 500.
 	serverErrorLevel zerolog.Level
-	// the log level to use for a specific path with status code < 400
+	// pathLevels is a map of specific paths to log levels for requests with status code < 400.
 	pathLevels map[string]zerolog.Level
 }
 
 const loggerKey = "_gin-contrib/logger_"
 
 var isTerm bool = isatty.IsTerminal(os.Stdout.Fd())
 
-// SetLogger initializes the logging middleware.
+// SetLogger returns a gin.HandlerFunc (middleware) that logs requests using zerolog.
+// It accepts a variadic number of Option functions to customize the logger's behavior.
+//
+// The logger configuration includes:
+// - defaultLevel: the default logging level (default: zerolog.InfoLevel).
+// - clientErrorLevel: the logging level for client errors (default: zerolog.WarnLevel).
+// - serverErrorLevel: the logging level for server errors (default: zerolog.ErrorLevel).
+// - output: the output writer for the logger (default: gin.DefaultWriter).
+// - skipPath: a list of paths to skip logging.
+// - skipPathRegexps: a list of regular expressions to skip logging for matching paths.
+// - logger: a custom logger function to use instead of the default logger.
+//
+// The middleware logs the following request details:
+// - method: the HTTP method of the request.
+// - path: the URL path of the request.
+// - ip: the client's IP address.
+// - user_agent: the User-Agent header of the request.
+// - status: the HTTP status code of the response.
+// - latency: the time taken to process the request.
+// - body_size: the size of the response body.
+//
+// The logging level for each request is determined based on the response status code:
+// - clientErrorLevel for 4xx status codes.
+// - serverErrorLevel for 5xx status codes.
+// - defaultLevel for other status codes.
+// - Custom levels can be set for specific paths using the pathLevels configuration.
 func SetLogger(opts ...Option) gin.HandlerFunc {
 	cfg := &config{
 		defaultLevel:     zerolog.InfoLevel,
@@ -156,13 +186,28 @@ func SetLogger(opts ...Option) gin.HandlerFunc {
 	}
 }
 
-// ParseLevel converts a level string into a zerolog Level value.
-// returns an error if the input string does not match known values.
+// ParseLevel parses a string representation of a log level and returns the corresponding zerolog.Level.
+// It takes a single argument:
+//   - levelStr: a string representing the log level (e.g., "debug", "info", "warn", "error").
+//
+// It returns:
+//   - zerolog.Level: the parsed log level.
+//   - error: an error if the log level string is invalid.
 func ParseLevel(levelStr string) (zerolog.Level, error) {
 	return zerolog.ParseLevel(levelStr)
 }
 
-// Get return the logger associated with a gin context
+// Get retrieves the zerolog.Logger instance from the given gin.Context.
+// It assumes that the logger has been previously set in the context with the key loggerKey.
+// If the logger is not found, it will panic.
+//
+// Parameters:
+//
+//	c - the gin.Context from which to retrieve the logger.
+//
+// Returns:
+//
+//	zerolog.Logger - the logger instance stored in the context.
 func Get(c *gin.Context) zerolog.Logger {
 	return c.MustGet(loggerKey).(zerolog.Logger)
 }