From 0ad82c9337af4983ce4d1271ef275979a9eee27f Mon Sep 17 00:00:00 2001
From: Felix Deierlein <felix.deierlein@bit.admin.ch>
Date: Wed, 26 Jan 2022 18:08:28 +0100
Subject: [PATCH] docs: Add doc comments

---
 async.go                    | 1 -
 chaos/blockingswitchable.go | 4 ++++
 chaos/failingswitchable.go  | 4 ++++
 chaos/switchable.go         | 4 ++++
 delegating.go               | 1 +
 discard.go                  | 1 +
 enveloping.go               | 3 +++
 fallback.go                 | 4 ++--
 writer.go                   | 1 +
 9 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/async.go b/async.go
index 322b593..fba1ebf 100644
--- a/async.go
+++ b/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
diff --git a/chaos/blockingswitchable.go b/chaos/blockingswitchable.go
index 992e6d3..9bed1a2 100644
--- a/chaos/blockingswitchable.go
+++ b/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()
diff --git a/chaos/failingswitchable.go b/chaos/failingswitchable.go
index a8b0e1f..f6f2637 100644
--- a/chaos/failingswitchable.go
+++ b/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
 }
diff --git a/chaos/switchable.go b/chaos/switchable.go
index 16e940e..abbbb7a 100644
--- a/chaos/switchable.go
+++ b/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()
 }
diff --git a/delegating.go b/delegating.go
index f6c9187..32cdb57 100644
--- a/delegating.go
+++ b/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
diff --git a/discard.go b/discard.go
index c6ed816..c1e2c6e 100644
--- a/discard.go
+++ b/discard.go
@@ -6,6 +6,7 @@ import (
 
 var _ SynchronizationAwareAppender = &Discard{}
 
+// Discard silently drops all messages
 type Discard struct {
 }
 
diff --git a/enveloping.go b/enveloping.go
index 5285413..03edd17 100644
--- a/enveloping.go
+++ b/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
diff --git a/fallback.go b/fallback.go
index 5b8d055..75482e3 100644
--- a/fallback.go
+++ b/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,
diff --git a/writer.go b/writer.go
index ba875d6..33e6fbc 100644
--- a/writer.go
+++ b/writer.go
@@ -8,6 +8,7 @@ import (
 
 var _ Appender = &Writer{}
 
+// Writer outputs the message to a zapcore.WriteSyncer
 type Writer struct {
 	out zapcore.WriteSyncer
 }