improve doc

samber · Apr 16, 2023 · ca555f6 · ca555f6
1 parent f15bbd7
commit ca555f6
Show file tree

Hide file tree

Showing 10 changed files with 47 additions and 6 deletions.
diff --git a/failover.go b/failover.go
@@ -12,6 +12,7 @@ type FailoverHandler struct {
  handlers []slog.Handler
 }
 
+// Failover forward record to the first available slog.Handler
 func Failover() func(...slog.Handler) slog.Handler {
  return func(handlers ...slog.Handler) slog.Handler {
  return &FailoverHandler{
@@ -20,6 +21,7 @@ func Failover() func(...slog.Handler) slog.Handler {
  }
 }
 
+// Implements slog.Handler
 func (h *FailoverHandler) Enabled(ctx context.Context, l slog.Level) bool {
  for i := range h.handlers {
  if h.handlers[i].Enabled(ctx, l) {
@@ -30,6 +32,7 @@ func (h *FailoverHandler) Enabled(ctx context.Context, l slog.Level) bool {
  return false
 }
 
+// Implements slog.Handler
 func (h *FailoverHandler) Handle(ctx context.Context, r slog.Record) error {
  var err error
 
@@ -47,13 +50,15 @@ func (h *FailoverHandler) Handle(ctx context.Context, r slog.Record) error {
  return err
 }
 
+// Implements slog.Handler
 func (h *FailoverHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithAttrs(attrs)
  })
  return Failover()(handers...)
 }
 
+// Implements slog.Handler
 func (h *FailoverHandler) WithGroup(name string) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithGroup(name)

diff --git a/middleware.go b/middleware.go
@@ -4,4 +4,5 @@ import (
  "golang.org/x/exp/slog"
 )
 
+// Middleware defines the handler used by slog.Handler as return value.
 type Middleware func(slog.Handler) slog.Handler
diff --git a/middleware_inline.go b/middleware_inline.go
@@ -6,7 +6,7 @@ import (
  "golang.org/x/exp/slog"
 )
 
-// Shortcut to a middleware that implements all methods.
+// NewInlineMiddleware is a shortcut to a middleware that implements all methods.
 func NewInlineMiddleware(
  enabledFunc func(ctx context.Context, level slog.Level, next func(context.Context, slog.Level) bool) bool,
  handleFunc func(ctx context.Context, record slog.Record, next func(context.Context, slog.Record) error) error,
@@ -32,14 +32,17 @@ type InlineMiddleware struct {
  withGroupFunc func(name string, next func(string) slog.Handler) slog.Handler
 }
 
+// Implements slog.Handler
 func (h *InlineMiddleware) Enabled(ctx context.Context, level slog.Level) bool {
  return h.enabledFunc(ctx, level, h.next.Enabled)
 }
 
+// Implements slog.Handler
 func (h *InlineMiddleware) Handle(ctx context.Context, record slog.Record) error {
  return h.handleFunc(ctx, record, h.next.Handle)
 }
 
+// Implements slog.Handler
 func (h *InlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  return NewInlineMiddleware(
  h.enabledFunc,
@@ -49,6 +52,7 @@ func (h *InlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  )(h.withAttrsFunc(attrs, h.next.WithAttrs))
 }
 
+// Implements slog.Handler
 func (h *InlineMiddleware) WithGroup(name string) slog.Handler {
  return NewInlineMiddleware(
  h.enabledFunc,

diff --git a/middleware_inline_enabled.go b/middleware_inline_enabled.go
@@ -6,7 +6,7 @@ import (
  "golang.org/x/exp/slog"
 )
 
-// Shortcut to a middleware that implements only the `Enable` method.
+// NewEnabledInlineMiddleware is shortcut to a middleware that implements only the `Enable` method.
 func NewEnabledInlineMiddleware(enabledFunc func(ctx context.Context, level slog.Level, next func(context.Context, slog.Level) bool) bool) Middleware {
  return func(next slog.Handler) slog.Handler {
  return &EnabledInlineMiddleware{
@@ -22,18 +22,22 @@ type EnabledInlineMiddleware struct {
  enabledFunc func(context.Context, slog.Level, func(context.Context, slog.Level) bool) bool
 }
 
+// Implements slog.Handler
 func (h *EnabledInlineMiddleware) Enabled(ctx context.Context, level slog.Level) bool {
  return h.enabledFunc(ctx, level, h.next.Enabled)
 }
 
+// Implements slog.Handler
 func (h *EnabledInlineMiddleware) Handle(ctx context.Context, record slog.Record) error {
  return h.next.Handle(ctx, record)
 }
 
+// Implements slog.Handler
 func (h *EnabledInlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  return NewEnabledInlineMiddleware(h.enabledFunc)(h.next.WithAttrs(attrs))
 }
 
+// Implements slog.Handler
 func (h *EnabledInlineMiddleware) WithGroup(name string) slog.Handler {
  return NewEnabledInlineMiddleware(h.enabledFunc)(h.next.WithGroup(name))
 }
diff --git a/middleware_inline_handle.go b/middleware_inline_handle.go
@@ -6,7 +6,7 @@ import (
  "golang.org/x/exp/slog"
 )
 
-// Shortcut to a middleware that implements only the `Handle` method.
+// NewHandleInlineMiddleware is a shortcut to a middleware that implements only the `Handle` method.
 func NewHandleInlineMiddleware(handleFunc func(ctx context.Context, record slog.Record, next func(context.Context, slog.Record) error) error) Middleware {
  return func(next slog.Handler) slog.Handler {
  return &HandleInlineMiddleware{
@@ -21,18 +21,22 @@ type HandleInlineMiddleware struct {
  handleFunc func(ctx context.Context, record slog.Record, next func(context.Context, slog.Record) error) error
 }
 
+// Implements slog.Handler
 func (h *HandleInlineMiddleware) Enabled(ctx context.Context, level slog.Level) bool {
  return h.next.Enabled(ctx, level)
 }
 
+// Implements slog.Handler
 func (h *HandleInlineMiddleware) Handle(ctx context.Context, record slog.Record) error {
  return h.handleFunc(ctx, record, h.next.Handle)
 }
 
+// Implements slog.Handler
 func (h *HandleInlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  return NewHandleInlineMiddleware(h.handleFunc)(h.next.WithAttrs(attrs))
 }
 
+// Implements slog.Handler
 func (h *HandleInlineMiddleware) WithGroup(name string) slog.Handler {
  return NewHandleInlineMiddleware(h.handleFunc)(h.next.WithGroup(name))
 }
diff --git a/middleware_inline_with_attrs.go b/middleware_inline_with_attrs.go
@@ -6,7 +6,7 @@ import (
  "golang.org/x/exp/slog"
 )
 
-// Shortcut to a middleware that implements only the `WithAttrs` method.
+// NewWithAttrsInlineMiddleware is a shortcut to a middleware that implements only the `WithAttrs` method.
 func NewWithAttrsInlineMiddleware(withAttrsFunc func(attrs []slog.Attr, next func([]slog.Attr) slog.Handler) slog.Handler) Middleware {
  return func(next slog.Handler) slog.Handler {
  return &WithAttrsInlineMiddleware{
@@ -21,18 +21,22 @@ type WithAttrsInlineMiddleware struct {
  withAttrsFunc func(attrs []slog.Attr, next func([]slog.Attr) slog.Handler) slog.Handler
 }
 
+// Implements slog.Handler
 func (h *WithAttrsInlineMiddleware) Enabled(ctx context.Context, level slog.Level) bool {
  return h.next.Enabled(ctx, level)
 }
 
+// Implements slog.Handler
 func (h *WithAttrsInlineMiddleware) Handle(ctx context.Context, record slog.Record) error {
  return h.next.Handle(ctx, record)
 }
 
+// Implements slog.Handler
 func (h *WithAttrsInlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  return NewWithAttrsInlineMiddleware(h.withAttrsFunc)(h.withAttrsFunc(attrs, h.next.WithAttrs))
 }
 
+// Implements slog.Handler
 func (h *WithAttrsInlineMiddleware) WithGroup(name string) slog.Handler {
  return NewWithAttrsInlineMiddleware(h.withAttrsFunc)(h.next.WithGroup(name))
 }
diff --git a/middleware_inline_with_group.go b/middleware_inline_with_group.go
@@ -6,7 +6,7 @@ import (
  "golang.org/x/exp/slog"
 )
 
-// Shortcut to a middleware that implements only the `WithAttrs` method.
+// NewWithGroupInlineMiddleware is a shortcut to a middleware that implements only the `WithAttrs` method.
 func NewWithGroupInlineMiddleware(withGroupFunc func(name string, next func(string) slog.Handler) slog.Handler) Middleware {
  return func(next slog.Handler) slog.Handler {
  return &WithGroupInlineMiddleware{
@@ -21,18 +21,22 @@ type WithGroupInlineMiddleware struct {
  withGroupFunc func(name string, next func(string) slog.Handler) slog.Handler
 }
 
+// Implements slog.Handler
 func (h *WithGroupInlineMiddleware) Enabled(ctx context.Context, level slog.Level) bool {
  return h.next.Enabled(ctx, level)
 }
 
+// Implements slog.Handler
 func (h *WithGroupInlineMiddleware) Handle(ctx context.Context, record slog.Record) error {
  return h.next.Handle(ctx, record)
 }
 
+// Implements slog.Handler
 func (h *WithGroupInlineMiddleware) WithAttrs(attrs []slog.Attr) slog.Handler {
  return NewWithGroupInlineMiddleware(h.withGroupFunc)(h.next.WithAttrs(attrs))
 }
 
+// Implements slog.Handler
 func (h *WithGroupInlineMiddleware) WithGroup(name string) slog.Handler {
  return NewWithGroupInlineMiddleware(h.withGroupFunc)(h.withGroupFunc(name, h.next.WithGroup))
 }
diff --git a/multi.go b/multi.go
@@ -11,12 +11,14 @@ type FanoutHandler struct {
  handlers []slog.Handler
 }
 
+// Fanout distributes records to multiple slog.Handler in parallel
 func Fanout(handlers ...slog.Handler) slog.Handler {
  return &FanoutHandler{
  handlers: handlers,
  }
 }
 
+// Implements slog.Handler
 func (h *FanoutHandler) Enabled(ctx context.Context, l slog.Level) bool {
  for i := range h.handlers {
  if h.handlers[i].Enabled(ctx, l) {
@@ -27,6 +29,7 @@ func (h *FanoutHandler) Enabled(ctx context.Context, l slog.Level) bool {
  return false
 }
 
+// Implements slog.Handler
 // @TODO: return multiple errors ?
 func (h *FanoutHandler) Handle(ctx context.Context, r slog.Record) error {
  for i := range h.handlers {
@@ -43,13 +46,15 @@ func (h *FanoutHandler) Handle(ctx context.Context, r slog.Record) error {
  return nil
 }
 
+// Implements slog.Handler
 func (h *FanoutHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithAttrs(attrs)
  })
  return Fanout(handers...)
 }
 
+// Implements slog.Handler
 func (h *FanoutHandler) WithGroup(name string) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithGroup(name)

diff --git a/pipe.go b/pipe.go
@@ -4,19 +4,24 @@ import (
  "golang.org/x/exp/slog"
 )
 
+// Pipe defines a chain of Middleware.
 type PipeBuilder struct {
  middlewares []Middleware
 }
 
+// Pipe builds a chain of Middleware.
+// Eg: rewrite log.Record on the fly for privacy reason.
 func Pipe(middlewares ...Middleware) *PipeBuilder {
  return &PipeBuilder{middlewares: middlewares}
 }
 
+// Implements slog.Handler
 func (h *PipeBuilder) Pipe(middleware Middleware) *PipeBuilder {
  h.middlewares = append(h.middlewares, middleware)
  return h
 }
 
+// Implements slog.Handler
 func (h *PipeBuilder) Handler(handler slog.Handler) slog.Handler {
  for len(h.middlewares) > 0 {
  middleware := h.middlewares[len(h.middlewares)-1]

diff --git a/pool.go b/pool.go
@@ -14,7 +14,8 @@ type PoolHandler struct {
  handlers []slog.Handler
 }
 
-// Uses a round robin strategy
+// Pool balances records between multiple slog.Handler in order to increase bandwidth.
+// Uses a round robin strategy.
 func Pool() func(...slog.Handler) slog.Handler {
  return func(handlers ...slog.Handler) slog.Handler {
  return &PoolHandler{
@@ -24,6 +25,7 @@ func Pool() func(...slog.Handler) slog.Handler {
  }
 }
 
+// Implements slog.Handler
 func (h *PoolHandler) Enabled(ctx context.Context, l slog.Level) bool {
  for i := range h.handlers {
  if h.handlers[i].Enabled(ctx, l) {
@@ -34,6 +36,7 @@ func (h *PoolHandler) Enabled(ctx context.Context, l slog.Level) bool {
  return false
 }
 
+// Implements slog.Handler
 func (h *PoolHandler) Handle(ctx context.Context, r slog.Record) error {
  // round robin
  rand := h.randSource.Int63() % int64(len(h.handlers))
@@ -55,13 +58,15 @@ func (h *PoolHandler) Handle(ctx context.Context, r slog.Record) error {
  return err
 }
 
+// Implements slog.Handler
 func (h *PoolHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithAttrs(attrs)
  })
  return Pool()(handers...)
 }
 
+// Implements slog.Handler
 func (h *PoolHandler) WithGroup(name string) slog.Handler {
  handers := lo.Map(h.handlers, func(h slog.Handler, _ int) slog.Handler {
  return h.WithGroup(name)