docs(onelog): improve go.doc and comments

nikoksr · Jul 22, 2023 · 2dd24ee · 2dd24ee
1 parent d846208
commit 2dd24ee
Show file tree

Hide file tree

Showing 10 changed files with 137 additions and 41 deletions.
diff --git a/adapter/nop/doc.go b/adapter/nop/doc.go
diff --git a/adapter/slog/adapter.go b/adapter/slog/adapter.go
@@ -520,7 +520,7 @@ func (c *Context) Fields(fields onelog.Fields) onelog.LoggerContext {
 	return c
 }
 
-// Msg writes the message and fields to the logger.
+// Msg sends the LoggerContext with msg to the logger.
 func (c *Context) Msg(msg string) {
 	if c == nil {
 		return
@@ -530,7 +530,7 @@ func (c *Context) Msg(msg string) {
 	c.fields = make([]slog.Attr, 0) // reset fields
 }
 
-// Msgf writes the formatted message and fields to the logger.
+// Msgf sends the LoggerContext with formatted msg to the logger.
 func (c *Context) Msgf(format string, v ...any) {
 	if c == nil {
 		return

diff --git a/adapter/slog/doc.go b/adapter/slog/doc.go
diff --git a/adapter/zap/adapter.go b/adapter/zap/adapter.go
@@ -516,7 +516,7 @@ func (c *Context) Fields(fields onelog.Fields) onelog.LoggerContext {
 	return c
 }
 
-// Msg writes the message and fields to the logger.
+// Msg sends the LoggerContext with msg to the logger.
 func (c *Context) Msg(msg string) {
 	if c == nil {
 		return
@@ -526,7 +526,7 @@ func (c *Context) Msg(msg string) {
 	c.fields = make([]zapcore.Field, 0) // reset fields
 }
 
-// Msgf writes the formatted message and fields to the logger.
+// Msgf sends the LoggerContext with formatted msg to the logger.
 func (c *Context) Msgf(format string, v ...any) {
 	if c == nil {
 		return

diff --git a/adapter/zap/doc.go b/adapter/zap/doc.go
diff --git a/adapter/zap/sugared_adapter.go b/adapter/zap/sugared_adapter.go
@@ -531,7 +531,7 @@ func (c *SugarContext) Fields(fields onelog.Fields) onelog.LoggerContext {
 	return c
 }
 
-// Msg writes the message and fields to the logger.
+// Msg sends the LoggerContext with msg to the logger.
 func (c *SugarContext) Msg(msg string) {
 	if c == nil {
 		return
@@ -552,7 +552,7 @@ func (c *SugarContext) Msg(msg string) {
 	c.fields = make([]any, 0) // reset fields
 }
 
-// Msgf writes the formatted message and fields to the logger.
+// Msgf sends the LoggerContext with formatted msg to the logger.
 func (c *SugarContext) Msgf(format string, v ...any) {
 	if c == nil {
 		return

diff --git a/adapter/zerolog/adapter.go b/adapter/zerolog/adapter.go
@@ -518,7 +518,7 @@ func (c *Context) Fields(fields onelog.Fields) onelog.LoggerContext {
 	return c
 }
 
-// Msg sends the logger context with level DEBUG.
+// Msg sends the LoggerContext with msg to the logger.
 func (c *Context) Msg(msg string) {
 	if c == nil {
 		return
@@ -527,7 +527,7 @@ func (c *Context) Msg(msg string) {
 	c.event.Msg(msg)
 }
 
-// Msgf sends the logger context with level DEBUG.
+// Msgf sends the LoggerContext with formatted msg to the logger.
 func (c *Context) Msgf(format string, v ...any) {
 	if c == nil {
 		return

diff --git a/adapter/zerolog/doc.go b/adapter/zerolog/doc.go
diff --git a/doc.go b/doc.go
@@ -1,6 +1,40 @@
-// Package onelog is a simple, versatile and performance-conscious logging interface that aims to provide a common base
-// for structured logging in Go. It supports adapters for multiple logging libraries, providing the flexibility to
-// switch between different loggers according to the requirements without changing the application’s logging interface
-// code. This package includes adapters for zap, zap's sugared logger, slog, and zerolog among others, supporting a
-// variety of logging styles and functionalities.
+// Package onelog is a general-purpose logging interface heavily inspired by the zerolog API.
+// It is designed to provide a user-friendly API for diverse logging requirements. This package
+// supports a wide range of data types and log levels, creating flexibility for various use cases.
+//
+// onelog includes adapters for several commonly used loggers, enabling easy integration
+// and compatibility with existing logging methodologies. It reduces the friction associated
+// with logging setup and promotes consistency in logging across different parts of a project or across different projects.
+//
+// Here is a brief example using the zapadapter and slogadapter:
+
+//			import (
+//		        "go.uber.org/zap"
+//		        "github.com/nikoksr/onelog"
+//		        "github.com/nikoksr/onelog/zapadapter"
+//		        "github.com/nikoksr/onelog/slogadapter"
+//			)
+//
+//			type superTracker struct {
+//		     superEventLogger onelog.Logger
+//			}
+//
+//			func main() {
+//		        // Let's use zap's development logger as our superhero event logger
+//		        logger, _ := zap.NewDevelopment()
+//
+//		        tracker := &superTracker{
+//		            superEventLogger: zapadapter.NewAdapter(logger),
+//		        }
+//
+//		        // Now let's log a superhero event
+//		        tracker.superEventLogger.Info().Msg("Superman spotted in New York!")
+//
+//		        // Or perhaps we'd rather use slog for logging our superhero sightings
+//		        logger := slog.Default()
+//		        tracker.superEventLogger = slogadapter.NewAdapter(logger)
+//
+//	         // And now we can log another sighting
+//	         tracker.superEventLogger.Info().Msg("Wonder Woman seen flying over Paris!")
+//			}
 package onelog
diff --git a/onelog.go b/onelog.go
@@ -5,66 +5,155 @@ import (
 	"time"
 )
 
-// Fields is a helper type for providing extra context in log messages.
+// Fields type is an alias for a map that stores key-value pairs.
 type Fields map[string]any
 
+// Logger interface provides methods for logging at various levels.
 type Logger interface {
+	// Debug returns a LoggerContext for a debug log.
 	Debug() LoggerContext
+
+	// Info returns a LoggerContext for an info log.
 	Info() LoggerContext
+
+	// Warn returns a LoggerContext for a warn log.
 	Warn() LoggerContext
+
+	// Error returns a LoggerContext for an error log.
 	Error() LoggerContext
+
+	// Fatal returns a LoggerContext for a fatal log.
 	Fatal() LoggerContext
 }
 
+// LoggerContext interface provides methods for adding context to logs.
 type LoggerContext interface {
+	// Str adds the field key with val as a string to the logger context.
 	Str(key, value string) LoggerContext
+
+	// Strs adds the field key with val as a []string to the logger context.
 	Strs(key string, value []string) LoggerContext
 
+	// Int adds the field key with val as an int to the logger context.
 	Int(key string, value int) LoggerContext
+
+	// Ints adds the field key with val as a []int to the logger context.
 	Ints(key string, value []int) LoggerContext
+
+	// Int8 adds the field key with val as an int8 to the logger context.
 	Int8(key string, value int8) LoggerContext
+
+	// Ints8 adds the field key with val as a []int8 to the logger context.
 	Ints8(key string, value []int8) LoggerContext
+
+	// Int16 adds the field key with val as an int16 to the logger context.
 	Int16(key string, value int16) LoggerContext
+
+	// Ints16 adds the field key with val as a []int16 to the logger context.
 	Ints16(key string, value []int16) LoggerContext
+
+	// Int32 adds the field key with val as an int32 to the logger context.
 	Int32(key string, value int32) LoggerContext
+
+	// Ints32 adds the field key with val as a []int32 to the logger context.
 	Ints32(key string, value []int32) LoggerContext
+
+	// Int64 adds the field key with val as an int64 to the logger context.
 	Int64(key string, value int64) LoggerContext
+
+	// Ints64 adds the field key with val as a []int64 to the logger context.
 	Ints64(key string, value []int64) LoggerContext
+
+	// Uint adds the field key with val as a uint to the logger context.
 	Uint(key string, value uint) LoggerContext
+
+	// Uints adds the field key with val as a []uint to the logger context.
 	Uints(key string, value []uint) LoggerContext
+
+	// Uint8 adds the field key with val as a uint8 to the logger context.
 	Uint8(key string, value uint8) LoggerContext
+
+	// Uints8 adds the field key with val as a []uint8 to the logger context.
 	Uints8(key string, value []uint8) LoggerContext
+
+	// Uint16 adds the field key with val as a uint16 to the logger context.
 	Uint16(key string, value uint16) LoggerContext
+
+	// Uints16 adds the field key with val as a []uint16 to the logger context.
 	Uints16(key string, value []uint16) LoggerContext
+
+	// Uint32 adds the field key with val as a uint32 to the logger context.
 	Uint32(key string, value uint32) LoggerContext
+
+	// Uints32 adds the field key with val as a []uint32 to the logger context.
 	Uints32(key string, value []uint32) LoggerContext
+
+	// Uint64 adds the field key with val as a uint64 to the logger context.
 	Uint64(key string, value uint64) LoggerContext
+
+	// Uints64 adds the field key with val as a []uint64 to the logger context.
 	Uints64(key string, value []uint64) LoggerContext
+
+	// Float32 adds the field key with val as a float32 to the logger context.
 	Float32(key string, value float32) LoggerContext
+
+	// Floats32 adds the field key with val as a []float32 to the logger context.
 	Floats32(key string, value []float32) LoggerContext
+
+	// Float64 adds the field key with val as a float64 to the logger context.
 	Float64(key string, value float64) LoggerContext
+
+	// Floats64 adds the field key with val as a []float64 to the logger context.
 	Floats64(key string, value []float64) LoggerContext
 
+	// Bool adds the field key with val as a bool to the logger context.
 	Bool(key string, value bool) LoggerContext
+
+	// Bools adds the field key with val as a []bool to the logger context.
 	Bools(key string, value []bool) LoggerContext
 
+	// Time adds the field key with val as a time.Time to the logger context.
 	Time(key string, value time.Time) LoggerContext
+
+	// Times adds the field key with val as a []time.Time to the logger context.
 	Times(key string, value []time.Time) LoggerContext
+
+	// Dur adds the field key with val as a time.Duration to the logger context.
 	Dur(key string, value time.Duration) LoggerContext
+
+	// Durs adds the field key with val as a []time.Duration to the logger context.
 	Durs(key string, value []time.Duration) LoggerContext
+
+	// TimeDiff adds the field key with val as duration between t and start to the logger context.
 	TimeDiff(key string, t time.Time, start time.Time) LoggerContext
 
+	// IPAddr adds the field key with val as a net.IP to the logger context.
 	IPAddr(key string, value net.IP) LoggerContext
+
+	// IPPrefix adds the field key with val as a net.IPNet to the logger context.
 	IPPrefix(key string, value net.IPNet) LoggerContext
+
+	// MACAddr adds the field key with val as a net.HardwareAddr to the logger context.
 	MACAddr(key string, value net.HardwareAddr) LoggerContext
 
+	// Err adds the key "error" with val as an error to the logger context.
 	Err(err error) LoggerContext
+
+	// Errs adds the field key with val as a []error to the logger context.
 	Errs(key string, errs []error) LoggerContext
+
+	// AnErr adds the field key with val as an error to the logger context.
 	AnErr(key string, err error) LoggerContext
 
+	// Any adds the field key with val as an interface{} to the logger context.
 	Any(key string, value any) LoggerContext
+
+	// Fields adds the field key with val as a Fields to the logger context.
 	Fields(fields Fields) LoggerContext
 
+	// Msg sends the LoggerContext with msg to the logger.
 	Msg(msg string)
+
+	// Msgf sends the LoggerContext with formatted msg to the logger.
 	Msgf(format string, v ...any)
 }