docs: add godoc and bilingual README

writers.go

@@ -10,12 +10,14 @@ import (
 	"time"
 )
 
+// LoggerWriter is the common sink interface used by Logger.
 type LoggerWriter interface {
 	Close() error
 	Write(p []byte) (n int, err error)
 	Print(level LogLevel, prefix string, traceback []*MethodTraceback, messages ...any) error
 }
 
+// LoggerTextWriter writes human-readable log records to an io.Writer.
 type LoggerTextWriter struct {
 	LoggerWriter
 	writer         io.Writer
@@ -24,14 +26,19 @@ type LoggerTextWriter struct {
 	printTime      bool
 }
 
+// Write forwards raw bytes to the underlying writer.
 func (w *LoggerTextWriter) Write(p []byte) (n int, err error) {
 	return w.writer.Write(p)
 }
+
+// Print formats the provided record as text and writes it to the underlying writer.
 func (w *LoggerTextWriter) Print(level LogLevel, prefix string, _ []*MethodTraceback, messages ...any) error {
 	s := BuildString(level, prefix, w.printTime, w.printTraceback, messages...)
 	_, err := w.Write([]byte(s))
 	return err
 }
+
+// Close closes the owned writer, if any.
 func (w *LoggerTextWriter) Close() error {
 	if w.closer == nil {
 		return nil
@@ -39,13 +46,15 @@ func (w *LoggerTextWriter) Close() error {
 	return w.closer.Close()
 }
 
-// LoggerJsonWriter write into writer JSON
+// LoggerJsonWriter writes structured log records as JSON.
 type LoggerJsonWriter struct {
 	LoggerWriter
 	writer io.Writer
 	closer io.Closer
 	pretty bool
 }
+
+// LoggerJsonMessage is the JSON payload emitted by LoggerJsonWriter.
 type LoggerJsonMessage struct {
 	Time      time.Time          `json:"time"`
 	Level     string             `json:"level"`
@@ -54,9 +63,12 @@ type LoggerJsonMessage struct {
 	Traceback []*MethodTraceback `json:"traceback"`
 }
 
+// Write forwards raw bytes to the underlying writer.
 func (w *LoggerJsonWriter) Write(data []byte) (int, error) {
 	return w.writer.Write(data)
 }
+
+// Print encodes the provided record as JSON and writes it to the underlying writer.
 func (w *LoggerJsonWriter) Print(level LogLevel, prefix string, traceback []*MethodTraceback, messages ...any) error {
 	msg := Map(messages, func(el any) string {
 		return fmt.Sprintf("%v", el)
@@ -91,6 +103,8 @@ func (w *LoggerJsonWriter) Print(level LogLevel, prefix string, traceback []*Met
 	_, err = w.Write(data)
 	return err
 }
+
+// Close closes the owned writer, if any.
 func (w *LoggerJsonWriter) Close() error {
 	if w.closer == nil {
 		return nil
@@ -98,12 +112,17 @@ func (w *LoggerJsonWriter) Close() error {
 	return w.closer.Close()
 }
 
+// CreateTextWriter wraps an external writer for text output without taking
+// ownership of it.
 func CreateTextWriter(w io.Writer, printTraceback, printTime bool) *LoggerTextWriter {
 	writer := &LoggerTextWriter{
 		writer: w, printTraceback: printTraceback, printTime: printTime,
 	}
 	return writer
 }
+
+// CreateTextFileWriter creates a text writer for path, creating parent
+// directories as needed. The returned writer owns the opened file.
 func CreateTextFileWriter(path string, printTraceback, printTime bool) (*LoggerTextWriter, error) {
 	err := os.MkdirAll(filepath.Dir(path), os.ModePerm)
 	if err != nil {
@@ -117,23 +136,34 @@ func CreateTextFileWriter(path string, printTraceback, printTime bool) (*LoggerT
 	writer.closer = file
 	return writer, nil
 }
+
+// CreateTextStdoutWriter creates a text writer for os.Stdout without taking
+// ownership of stdout.
 func CreateTextStdoutWriter(printTraceback, printTime bool) *LoggerTextWriter {
 	writer := CreateTextWriter(os.Stdout, printTraceback, printTime)
 	writer.closer = nil
 	return writer
 }
 
+// CreateJsonWriter wraps an external writer for JSON output without taking
+// ownership of it.
 func CreateJsonWriter(w io.Writer, pretty bool) *LoggerJsonWriter {
 	writer := &LoggerJsonWriter{
 		writer: w, pretty: pretty,
 	}
 	return writer
 }
+
+// CreateJsonStdoutWriter creates a JSON writer for os.Stdout without taking
+// ownership of stdout.
 func CreateJsonStdoutWriter(pretty bool) *LoggerJsonWriter {
 	writer := CreateJsonWriter(os.Stdout, pretty)
 	writer.closer = nil
 	return writer
 }
+
+// CreateJsonFileWriter creates a JSON writer for path, creating parent
+// directories as needed. The returned writer owns the opened file.
 func CreateJsonFileWriter(path string, pretty bool) (*LoggerJsonWriter, error) {
 	err := os.MkdirAll(filepath.Dir(path), os.ModePerm)
 	if err != nil {