From d21e46e02d8b358954f4fc1050bb420ee326a412 Mon Sep 17 00:00:00 2001
From: Benjamin Elder <bentheelder@google.com>
Date: Sat, 7 Sep 2019 13:41:20 -0700
Subject: [PATCH] document logger interface

---
 pkg/log/types.go | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/pkg/log/types.go b/pkg/log/types.go
index 553b105b..875eabdf 100644
--- a/pkg/log/types.go
+++ b/pkg/log/types.go
@@ -23,17 +23,44 @@ type Level int32
 // Logger defines the logging interface kind uses
 // It is roughly a subset of github.com/kubernetes/klog
 type Logger interface {
+	// Warn should be used to write user facing warnings
 	Warn(message string)
+	// Warnf should be used to write Printf style user facing warnings
 	Warnf(format string, args ...interface{})
+	// Error may be used to write an error message when it occurs
+	// Prefer returning an error instead in most cases
 	Error(message string)
+	// Errorf may be used to write a Printf style error message when it occurs
+	// Prefer returning an error instead in most cases
 	Errorf(format string, args ...interface{})
+	// V() returns an InfoLogger for a given verbosity Level
+	//
+	// Normal verbosity levels:
+	// V(0): normal user facing messages go to V(0)
+	// V(1): debug messages start when V(N > 0), these should be high level
+	// V(2): more detailed log messages
+	// V(3+): trace level logging, in increasing "noisiness" ... allowing
+	// arbitrarily detailed logging at extremely low cost unless the
+	// logger has actually been configured to display these (E.G. via the -v
+	// command line flag)
+	//
+	// It is expected that the returned InfoLogger will be extremely cheap
+	// to interact with for a Level greater than the enabled level
 	V(Level) InfoLogger
 }
 
 // InfoLogger defines the info logging interface kind uses
 // It is roughly a subset of Verbose from github.com/kubernetes/klog
 type InfoLogger interface {
+	// Info is used to write a user facing status message
+	//
+	// See: Logger.V
 	Info(message string)
+	// Infof is used to write a Printf style user facing status message
 	Infof(format string, args ...interface{})
+	// Enabled should return true if this verbosity level is enabled
+	// on the Logger
+	//
+	// See: Logger.V
 	Enabled() bool
 }