(new): prepare v2.1.0 release

- add custom LogLevel constructors and richer color configuration
- support ANSI, 256-color, RGB, and text attributes on LogLevel
- introduce clearer preferred APIs such as NewLogger and SetName
- preserve backward compatibility with deprecated wrappers for v2.0.1 APIs
- restore legacy ColorStringBuilder signatures as compatibility wrappers
- fix newline separator handling in Println-style output
- add tests for color precedence, deprecated aliases, and LogLevel attributes
- update GoDoc and bilingual README documentation

formatter.go

@@ -47,6 +47,7 @@ var DefaultJsonFormatter = &Formatter{
 	ColorOutput:      false,
 }
 
+// NewFormatter returns a copy of the default text formatter settings.
 func NewFormatter() *Formatter {
 	return &Formatter{
 		Format:             DefaultTextFormatter.Format,
@@ -58,35 +59,50 @@ func NewFormatter() *Formatter {
 		ColorOnlyStdout:    DefaultTextFormatter.ColorOnlyStdout,
 	}
 }
+
+// SetFormat sets the formatter template used for text rendering.
 func (f *Formatter) SetFormat(format string) *Formatter {
 	f.Format = format
 	return f
 }
+
+// SetMessageSeparator sets the separator used to join message parts.
 func (f *Formatter) SetMessageSeparator(separator string) *Formatter {
 	f.MessageSeparator = separator
 	return f
 }
+
+// SetTimeStampFormat sets the strftime-like format used for timestamps.
 func (f *Formatter) SetTimeStampFormat(format string) *Formatter {
 	f.TimeStampFormat = format
 	return f
 }
+
+// SetTraceBackFormat sets the format used for a single traceback frame.
 func (f *Formatter) SetTraceBackFormat(format string) *Formatter {
 	f.TraceBackFormat = format
 	return f
 }
+
+// SetTraceBackSeparator sets the separator used between traceback frames.
 func (f *Formatter) SetTraceBackSeparator(separator string) *Formatter {
 	f.TraceBackSeparator = separator
 	return f
 }
+
+// SetColorOutput enables or disables colorized output.
 func (f *Formatter) SetColorOutput(color bool) *Formatter {
 	f.ColorOutput = color
 	return f
 }
+
+// SetColorOnlyStdout restricts colorized output to stdout and stderr when enabled.
 func (f *Formatter) SetColorOnlyStdout(only bool) *Formatter {
 	f.ColorOnlyStdout = only
 	return f
 }
 
+// FormatMessage applies the formatter template to the provided log record fields.
 func (f *Formatter) FormatMessage(level LogLevel, prefix string, tb []*MethodTraceback, messages ...any) string {
 	if f == nil {
 		return fmt.Sprint(messages...)
@@ -132,18 +148,40 @@ func (f *Formatter) FormatMessage(level LogLevel, prefix string, tb []*MethodTra
 	return output
 }
 
+// ColorizeString wraps a string in the ANSI color sequences defined by the level.
 func (f *Formatter) ColorizeString(s string, level LogLevel) string {
-	return NewColorStringBuilder().
-		AddFgColor(level.fg).AddBgColor(level.bg).
-		AddText(s).AddReset().String()
+	builder := NewColorStringBuilder()
+	if level.fgRgb != nil {
+		builder.AddForegroundRGB(level.fgRgb)
+	} else if level.fg256 > 0 {
+		builder.AddForeground256Color(level.fg256)
+	} else {
+		builder.AddFgColor(level.fg)
+	}
+
+	if level.bgRgb != nil {
+		builder.AddBackgroundRGB(level.bgRgb)
+	} else if level.bg256 > 0 {
+		builder.AddBackground256Color(level.bg256)
+	} else {
+		builder.AddBgColor(level.bg)
+	}
+
+	for _, attr := range level.attrs {
+		builder.AddAttribute(attr)
+	}
+	return builder.AddText(s).AddReset().String()
 }
 
+// FormatTime formats a timestamp using the formatter timestamp layout.
 func (f *Formatter) FormatTime(t time.Time) string {
 	if f.TimeStampFormat == "" {
 		return t.Format(time.RFC3339)
 	}
 	return t.Format(StrftimeToGo(f.TimeStampFormat))
 }
+
+// FormatTraceback formats a single traceback frame.
 func (f *Formatter) FormatTraceback(traceback *MethodTraceback) string {
 	formattedTraceback := f.TraceBackFormat
 	if f.JSONTraceBackPath {
@@ -157,6 +195,8 @@ func (f *Formatter) FormatTraceback(traceback *MethodTraceback) string {
 	formattedTraceback = strings.ReplaceAll(formattedTraceback, "%s", traceback.Signature)
 	return formattedTraceback
 }
+
+// FormatTracebacks formats and joins multiple traceback frames.
 func (f *Formatter) FormatTracebacks(traceback []*MethodTraceback) string {
 	var formattedTraceback []string
 	for _, frame := range traceback {