From 0dd890a09d8a6c3eeb9e78f178a9de4581d5e399 Mon Sep 17 00:00:00 2001
From: 9seconds <nineseconds@yandex.ru>
Date: Mon, 5 Apr 2021 16:55:26 +0300
Subject: [PATCH] Add documentation for logger

---
 logger/init.go    |  9 +++++++++
 logger/noop.go    |  1 +
 logger/zerolog.go |  1 +
 mtglib/init.go    | 22 ++++++++++++++++++++++
 4 files changed, 33 insertions(+)

diff --git a/logger/init.go b/logger/init.go
index afcaf1d..8ff8ddc 100644
--- a/logger/init.go
+++ b/logger/init.go
@@ -1,5 +1,14 @@
+// Package logger has implementation of loggers for mtglib.Logger
+// interface.
+//
+// Please see a description of that interface to get some agreements
+// which are used by mtglib.
 package logger
 
+// StdLikeLogger is an interface which is close to log.Logger. This is
+// commonly used by many 3pp tools. While mtglib itself does not need
+// it, it is always a good idea to support it and have a transient end
+// to end logging.
 type StdLikeLogger interface {
 	Printf(format string, args ...interface{})
 }
diff --git a/logger/noop.go b/logger/noop.go
index d416542..61470ac 100644
--- a/logger/noop.go
+++ b/logger/noop.go
@@ -15,6 +15,7 @@ func (n noopLogger) InfoError(_ string, _ error)           {}
 func (n noopLogger) WarningError(_ string, _ error)        {}
 func (n noopLogger) DebugError(_ string, _ error)          {}
 
+// NewNoopLogger returns a logger which discards all events.
 func NewNoopLogger() mtglib.Logger {
 	return noopLogger{}
 }
diff --git a/logger/zerolog.go b/logger/zerolog.go
index d504afa..b0dc0b6 100644
--- a/logger/zerolog.go
+++ b/logger/zerolog.go
@@ -114,6 +114,7 @@ func (z *zeroLogContext) attachCtx(evt *zerolog.Event) {
 	}
 }
 
+// NewZeroLogger returns a logger which is using rs/zerolog library.
 func NewZeroLogger(log zerolog.Logger) mtglib.Logger {
 	return &zeroLogContext{
 		log: &log,
diff --git a/mtglib/init.go b/mtglib/init.go
index ca69ed5..570cc1d 100644
--- a/mtglib/init.go
+++ b/mtglib/init.go
@@ -76,6 +76,8 @@ type AntiReplayCache interface {
 // a worker pool, so in worst cases you can expect that you invoke this
 // object more frequent than defined proxy concurrency.
 type IPBlocklist interface {
+	// Contains checks if given IP address belongs to this blocklist If.
+	// it is, a connection is terminated                               .
 	Contains(net.IP) bool
 }
 
@@ -107,6 +109,26 @@ type TimeAttackDetector interface {
 	Valid(time.Time) error
 }
 
+// Logger defines an interface of the logger used by mtglib.
+//
+// Each logger has a name. It is possible to stack names to organize
+// poor-man namespaces. Also, each logger must be able to bind
+// parameters to avoid pushing them all the time.
+//
+// Example
+//
+//     logger := SomeLogger{}
+//     logger = logger.BindStr("ip", net.IP{127, 0, 0, 1})
+//     logger.Info("Hello")
+//
+// In that case, ip is bound as a parameter. It is a great idea to
+// put this parameter somewhere in a log message.
+//
+//     logger1 = logger.BindStr("param1", "11")
+//     logger2 = logger.BindInt("param2", 11)
+//
+// logger1 should see no param2 and vice versa, logger2 should not see param1
+// If you attach a parameter to a logger, parents should not know about that.
 type Logger interface {
 	Named(name string) Logger