Merge pull request #119 from pohly/error-verbosity

docs: clarify Error semantic

logr.go

@@ -43,7 +43,9 @@ limitations under the License.
 //
 // Info() and Error() are very similar, but they are separate methods so that
 // LogSink implementations can choose to do things like attach additional
-// information (such as stack traces) on calls to Error().
+// information (such as stack traces) on calls to Error(). Error() messages are
+// always logged, regardless of the current verbosity.  If there is no error
+// instance available, passing nil is valid.
 //
 // Verbosity
 //
@@ -53,6 +55,7 @@ limitations under the License.
 // Log-lines with V-levels that are not enabled (as per the LogSink) will not
 // be written.  Level V(0) is the default, and logger.V(0).Info() has the same
 // meaning as logger.Info().  Negative V-levels have the same meaning as V(0).
+// Error messages do not have a verbosity level and are always logged.
 //
 // Where we might have written:
 //   if flVerbose >= 2 {
@@ -253,11 +256,13 @@ func (l Logger) Info(msg string, keysAndValues ...interface{}) {
 // Error logs an error, with the given message and key/value pairs as context.
 // It functions similarly to Info, but may have unique behavior, and should be
 // preferred for logging errors (see the package documentations for more
-// information).
+// information). The log message will always be emitted, regardless of
+// verbosity level.
 //
 // The msg argument should be used to add context to any underlying error,
 // while the err argument should be used to attach the actual error that
-// triggered this log line, if present.
+// triggered this log line, if present. The err parameter is optional
+// and nil may be passed instead of an error instance.
 func (l Logger) Error(err error, msg string, keysAndValues ...interface{}) {
 	if withHelper, ok := l.sink.(CallStackHelperLogSink); ok {
 		withHelper.GetCallStackHelper()()