Add documentation for logger

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{})
 }

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{}
 }

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,

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