👔 up: handler.Config add new option DebugMode, update some tests and …

…comments

README.md

@@ -340,9 +340,10 @@ f.SetTemplate(myTemplate)
 Custom `Processor` and `Formatter` are relatively simple, just implement a corresponding method.
 
 ### Create new logger
+
 `slog.Info, slog.Warn` and other methods use the default logger and output logs to the console by default.
 
-You can create a brand new instance of `slog.Logger`:
+You can create a brand-new instance of `slog.Logger`:
 
 **Method 1**：
 
@@ -468,7 +469,7 @@ import (
 )
 
 func main() {
-	defer slog.MustFlush()
+	defer slog.MustClose()
 
 	// DangerLevels contains: slog.PanicLevel, slog.ErrorLevel, slog.WarnLevel
 	h1 := handler.MustFileHandler("/tmp/error.log", handler.WithLogLevels(slog.DangerLevels))
@@ -490,7 +491,7 @@ func main() {
 }
 ```
 
-> Tip: If write buffering `buffer` is enabled, be sure to call `logger.Flush()` at the end of the program to flush the contents of the buffer to the file.
+> **Note**: If write buffering `buffer` is enabled, be sure to call `logger.Close()` at the end of the program to flush the contents of the buffer to the file.
 
 ### Log to file with automatic rotating
 

README.zh-CN.md

@@ -467,7 +467,7 @@ import (
 )
 
 func main() {
-	defer slog.MustFlush()
+	defer slog.MustClose()
 
 	// DangerLevels 包含： slog.PanicLevel, slog.ErrorLevel, slog.WarnLevel
 	h1 := handler.MustFileHandler("/tmp/error.log", handler.WithLogLevels(slog.DangerLevels))
@@ -489,7 +489,7 @@ func main() {
 }
 ```
 
-> 提示: 如果启用了写入缓冲 `buffer`，一定要在程序结束时调用 `logger.Flush()` 刷出缓冲区的内容到文件。
+> 提示: 如果启用了写入缓冲 `buffer`，一定要在程序结束时调用 `logger.Close()/MustClose()` 刷出缓冲区的内容到文件并关闭句柄。
 
 ### 带自动切割的日志处理器
 

example_test.go

@@ -67,6 +67,7 @@ func ExampleFlushDaemon() {
 
 	go slog.FlushDaemon(func() {
 		fmt.Println("flush daemon stopped")
+		slog.MustClose()
 		wg.Done()
 	})
 

formatter.go

@@ -32,6 +32,7 @@ type Formattable interface {
 type FormattableTrait = FormatterWrapper
 
 // FormatterWrapper use for format log record.
+// default use the TextFormatter
 type FormatterWrapper struct {
 	// if not set, default use the TextFormatter
 	formatter Formatter

handler/config.go

@@ -78,6 +78,9 @@ type Config struct {
 
 	// RenameFunc build filename for rotate file
 	RenameFunc func(filepath string, rotateNum uint) string
+
+	// DebugMode for debug on development.
+	DebugMode bool
 }
 
 // NewEmptyConfig new config instance
@@ -168,6 +171,7 @@ func (c *Config) CreateWriter() (output SyncCloseWriter, err error) {
 		rc.CloseLock = true
 		rc.Filepath = c.Logfile
 		rc.FilePerm = c.FilePerm
+		rc.DebugMode = c.DebugMode
 
 		// copy settings
 		rc.MaxSize = c.MaxSize

handler/handler_test.go

@@ -1,6 +1,7 @@
 package handler_test
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/gookit/goutil"
@@ -20,6 +21,7 @@ var (
 )
 
 func TestMain(m *testing.M) {
+	fmt.Println("TestMain: remove all test files in ./testdata")
 	goutil.PanicErr(fsutil.RemoveSub("./testdata", fsutil.ExcludeNames(".keep")))
 	m.Run()
 }

handler/rotatefile_test.go

@@ -30,7 +30,7 @@ func TestNewRotateFileHandler(t *testing.T) {
 		l.Info("info", "message", i)
 		l.Warn("warn message", i)
 	}
-	l.MustFlush()
+	l.MustClose()
 
 	// by time
 	logfile = "./testdata/both-rotate-bytime.log"
@@ -124,7 +124,7 @@ func TestNewTimeRotateFileHandler_EveryDay(t *testing.T) {
 		// time.Sleep(time.Second * 1)
 	}
 
-	l.MustFlush()
+	l.MustClose()
 	checkLogFileContents(t, logfile)
 	checkLogFileContents(t, newFile)
 }
@@ -170,7 +170,7 @@ func TestNewTimeRotateFileHandler_EveryHour(t *testing.T) {
 		sec++
 		fmt.Println("log number ", (i+1)*2)
 	}
-	l.MustFlush()
+	l.MustClose()
 
 	checkLogFileContents(t, logfile)
 	checkLogFileContents(t, newFile)
@@ -193,7 +193,7 @@ func TestNewTimeRotateFileHandler_someSeconds(t *testing.T) {
 		fmt.Println("second ", i+1)
 		time.Sleep(time.Second * 1)
 	}
-	l.MustFlush()
+	l.MustClose()
 	// assert.NoErr(t, os.Remove(fpath))
 }
 

issues_test.go

@@ -30,7 +30,7 @@ func TestIssues_27(t *testing.T) {
 // https://github.com/gookit/slog/issues/31
 func TestIssues_31(t *testing.T) {
 	defer slog.Reset()
-	defer slog.MustFlush()
+	defer slog.MustClose()
 
 	// slog.DangerLevels equals slog.Levels{slog.PanicLevel, slog.PanicLevel, slog.ErrorLevel, slog.WarnLevel}
 	h1 := handler.MustFileHandler("testdata/error_issue31.log", handler.WithLogLevels(slog.DangerLevels))

sugared.go

@@ -10,8 +10,7 @@ import (
 // SugaredLoggerFn func type.
 type SugaredLoggerFn func(sl *SugaredLogger)
 
-// SugaredLogger definition.
-// Is a fast and usable Logger, which already contains
+// SugaredLogger Is a fast and usable Logger, which already contains
 // the default formatting and handling capabilities
 type SugaredLogger struct {
 	*Logger
@@ -109,10 +108,14 @@ func (sl *SugaredLogger) Handle(record *Record) error {
 	return err
 }
 
-// Close all log handlers
+// Close all log handlers, will flush and close all handlers.
+//
+// IMPORTANT:
+//
+//	if enable async/buffer mode, please call the Close() before exit.
 func (sl *SugaredLogger) Close() error {
 	_ = sl.Logger.VisitAll(func(handler Handler) error {
-		// TIP: must exclude self
+		// TIP: must exclude self, because self is a handler
 		if _, ok := handler.(*SugaredLogger); !ok {
 			if err := handler.Close(); err != nil {
 				sl.err = err