docs: Add doc comments

async.go

@@ -12,7 +12,6 @@ import (
 	"go.uber.org/zap/zapcore"
 )
 
-// TODO: message structs could be used in general
 type writeMessage struct {
 	// TODO: create a custom []byte buffer instance so we do not need to keep the reference to the pool?
 	buf   *buffer.Buffer

chaos/blockingswitchable.go

@@ -13,6 +13,7 @@ var (
 	_ Switchable           = &BlockingSwitchable{}
 )
 
+// BlockingSwitchable allows to block all messages until it is released.
 type BlockingSwitchable struct {
 	primary zapappender.Appender
 	enabled bool
@@ -36,12 +37,14 @@ func NewBlockingSwitchableCtx(ctx context.Context, inner zapappender.Appender) *
 	}
 }
 
+// Breaking returns true if messages are currently blocked.
 func (a *BlockingSwitchable) Breaking() bool {
 	a.mu.Lock()
 	defer a.mu.Unlock()
 	return a.enabled
 }
 
+// Break blocks all messages until Fix is called.
 func (a *BlockingSwitchable) Break() {
 	a.mu.Lock()
 	defer a.mu.Unlock()
@@ -52,6 +55,7 @@ func (a *BlockingSwitchable) Break() {
 	a.waiting = make(chan struct{})
 }
 
+// Fix unblocks the messages.
 func (a *BlockingSwitchable) Fix() {
 	a.mu.Lock()
 	defer a.mu.Unlock()

chaos/failingswitchable.go

@@ -14,6 +14,7 @@ var (
 	_ Switchable           = &FailingSwitchable{}
 )
 
+// FailingSwitchable returns an error on all writes while it is Breaking.
 type FailingSwitchable struct {
 	primary zapappender.Appender
 	enabled bool
@@ -26,14 +27,17 @@ func NewFailingSwitchable(inner zapappender.Appender) *FailingSwitchable {
 	}
 }
 
+// Breaking returns true if FailingSwitchable is set to fail.
 func (a *FailingSwitchable) Breaking() bool {
 	return a.enabled
 }
 
+// Break starts failing messages.
 func (a *FailingSwitchable) Break() {
 	a.enabled = true
 }
 
+// Fix stops failing messages.
 func (a *FailingSwitchable) Fix() {
 	a.enabled = false
 }

chaos/switchable.go

@@ -1,7 +1,11 @@
 package chaos
 
+// Switchable is the base interface for chaos adapters created for testing.
 type Switchable interface {
+	// Breaking returns true if the failure behaviour is activated.
 	Breaking() bool
+	// Break starts the failure behaviour.
 	Break()
+	// Fix stops the failure behaviour.
 	Fix()
 }

delegating.go

@@ -6,6 +6,7 @@ import (
 
 var _ SynchronizationAwareAppender = &Delegating{}
 
+// Delegating delegates Write and Sync to functions
 type Delegating struct {
 	WriteFn           func(p []byte, ent zapcore.Entry) (n int, err error)
 	SyncFn            func() error

discard.go

@@ -6,6 +6,7 @@ import (
 
 var _ SynchronizationAwareAppender = &Discard{}
 
+// Discard silently drops all messages
 type Discard struct {
 }
 

enveloping.go

@@ -16,6 +16,9 @@ type EnvelopingFn func(p []byte, ent zapcore.Entry, output *buffer.Buffer) error
 
 var _ SynchronizationAwareAppender = &Enveloping{}
 
+// Enveloping allows to adapt the log message.
+// This can be used to format the message output. That is especially usefull when a format should only
+// be applied to a primary appender but not a fallback one.
 type Enveloping struct {
 	primary Appender
 	envFn   EnvelopingFn

fallback.go

@@ -7,13 +7,13 @@ import (
 
 var _ SynchronizationAwareAppender = &Fallback{}
 
+// Fallback forwards the message to secondary, if writing to primary returned an error.
+// secondary is wrapped in a Synchronizing appender.
 type Fallback struct {
 	primary   Appender
 	secondary Appender
 }
 
-// NewFallback forwards the message to secondary, if writing to primary returned an error.
-// secondary is wrapped in a Synchronizing zapappender.
 func NewFallback(primary, secondary Appender) *Fallback {
 	return &Fallback{
 		primary:   primary,

writer.go

@@ -8,6 +8,7 @@ import (
 
 var _ Appender = &Writer{}
 
+// Writer outputs the message to a zapcore.WriteSyncer
 type Writer struct {
 	out zapcore.WriteSyncer
 }