Add top-level API comments.

Author: knz

assert_api.go

@@ -16,11 +16,20 @@ package errors
 
 import "github.com/cockroachdb/errors/assert"
 
-// WithAssertionFailure forwards a definition.
+// WithAssertionFailure decorates the error with an assertion failure marker.
+// This is not intended to be used directly (see AssertionFailed() for
+// further decoration).
+//
+// Detail is shown:
+// - when formatting with `%+v`.
+// - in Sentry reports.
 func WithAssertionFailure(err error) error { return assert.WithAssertionFailure(err) }
 
-// HasAssertionFailure forwards a definition.
+// HasAssertionFailure returns true if the error or any of its causes
+// is an assertion failure annotation.
 func HasAssertionFailure(err error) bool { return assert.HasAssertionFailure(err) }
 
-// IsAssertionFailure forwards a definition.
+// IsAssertionFailure returns true if the error (not its causes) is an
+// assertion failure annotation. Consider using markers.If or
+// HasAssertionFailure to test both the error and its causes.
 func IsAssertionFailure(err error) bool { return assert.IsAssertionFailure(err) }

barriers_api.go

@@ -16,8 +16,19 @@ package errors
 
 import "github.com/cockroachdb/errors/barriers"
 
-// Handled forwards a definition.
+// Handled swallows the provided error and hides it from the
+// Cause()/Unwrap() interface, and thus the Is() facility that
+// identifies causes. However, it retains it for the purpose of
+// printing the error out (e.g. for troubleshooting). The error
+// message is preserved in full.
+//
+// Detail is shown:
+// - via `errors.GetSafeDetails()`, shows details from hidden error.
+// - when formatting with `%+v`.
+// - in Sentry reports.
 func Handled(err error) error { return barriers.Handled(err) }
 
-// HandledWithMessage forwards a definition.
+// HandledWithMessage is like Handled except the message is overridden.
+// This can be used e.g. to hide message details or to prevent
+// downstream code to make assertions on the message's contents.
 func HandledWithMessage(err error, msg string) error { return barriers.HandledWithMessage(err, msg) }

contexttags_api.go

@@ -21,10 +21,27 @@ import (
 	"github.com/cockroachdb/logtags"
 )
 
-// WithContextTags forwards a definition.
+// WithContextTags captures the k/v pairs stored in the context via the
+// `logtags` package and annotates them on the error.
+//
+// Only the stromg representation of values remains available. This is
+// because the library cannot guarantee that the underlying value is
+// preserved across the network. To avoid creating a stateful interface
+// (where the user code needs to know whether an error has traveled
+// through the network or not), the library restricts access to the
+// value part as strings. See GetContextTags() below.
+//
+// Detail is shown:
+// - via `errors.GetSafeDetails()`.
+// - via `GetContextTags()` below.
+// - when formatting with `%+v`.
+// - in Sentry reports.
 func WithContextTags(err error, ctx context.Context) error {
 	return contexttags.WithContextTags(err, ctx)
 }
 
-// GetContextTags forwards a definition.
+// GetContextTags retrieves the k/v pairs stored in the error.
+// The sets are returned from outermost to innermost level of cause.
+// The returned logtags.Buffer only know about the string
+// representation of the values originally captured by the error.
 func GetContextTags(err error) []*logtags.Buffer { return contexttags.GetContextTags(err) }

domains/domains.go

@@ -144,7 +144,7 @@ func PackageDomain() Domain {
 }
 
 // PackageDomainAtDepth returns an error domain that describes the
-// package at the given depth.
+// package at the given call depth.
 func PackageDomainAtDepth(depth int) Domain {
 	_, f, _, _ := runtime.Caller(1 + depth)
 	return Domain("error domain: pkg " + filepath.Dir(f))

domains_api.go

@@ -16,42 +16,63 @@ package errors
 
 import "github.com/cockroachdb/errors/domains"
 
-// Domain forwards a definition.
+// Domain is the type of a domain annotation.
 type Domain = domains.Domain
 
-// NoDomain forwards a definition.
+// NoDomain is the domain of errors that don't originate
+// from a barrier.
 const NoDomain Domain = domains.NoDomain
 
-// NamedDomain forwards a definition.
+// NamedDomain returns an error domain identified by the given string.
 func NamedDomain(domainName string) Domain { return domains.NamedDomain(domainName) }
 
-// PackageDomain forwards a definition.
+// PackageDomain returns an error domain that represents the
+// package of its caller.
 func PackageDomain() Domain { return domains.PackageDomainAtDepth(1) }
 
-// PackageDomainAtDepth forwards a definition.
+// PackageDomainAtDepth returns an error domain that describes the
+// package at the given call depth.
 func PackageDomainAtDepth(depth int) Domain { return domains.PackageDomainAtDepth(depth) }
 
-// WithDomain forwards a definition.
+// WithDomain wraps an error so that it appears to come from the given domain.
+//
+// Domain is shown:
+// - via `errors.GetSafeDetails()`.
+// - when formatting with `%+v`.
+// - in Sentry reports.
 func WithDomain(err error, domain Domain) error { return domains.WithDomain(err, domain) }
 
-// NotInDomain forwards a definition.
+// NotInDomain returns true if and only if the error's
+// domain is not one of the specified domains.
 func NotInDomain(err error, doms ...Domain) bool { return domains.NotInDomain(err, doms...) }
 
-// EnsureNotInDomain forwards a definition.
+// EnsureNotInDomain checks whether the error is in the given domain(s).
+// If it is, the given constructor if provided is called to construct
+// an alternate error. If no error constructor is provided,
+// a new barrier is constructed automatically using the first
+// provided domain as new domain. The original error message
+// is preserved.
 func EnsureNotInDomain(err error, constructor DomainOverrideFn, forbiddenDomains ...Domain) error {
 	return domains.EnsureNotInDomain(err, constructor, forbiddenDomains...)
 }
 
-// DomainOverrideFn forwards a definition.
+// DomainOverrideFn is the type of the callback function passed to EnsureNotInDomain().
 type DomainOverrideFn = func(originalDomain Domain, err error) error
 
-// HandledInDomain forwards a definition.
+// HandledInDomain creates an error in the given domain and retains
+// the details of the given original error as context for
+// debugging. The original error is hidden and does not become a
+// "cause" for the new error. The original's error _message_
+// is preserved.
+//
+// See the documentation of `WithDomain()` and `errors.Handled()` for details.
 func HandledInDomain(err error, domain Domain) error { return domains.HandledInDomain(err, domain) }
 
-// HandledInDomainWithMessage forwards a definition.
+// HandledInDomainWithMessage is like HandledWithMessage but with a domain.
 func HandledInDomainWithMessage(err error, domain Domain, msg string) error {
 	return domains.HandledInDomainWithMessage(err, domain, msg)
 }
 
-// GetDomain forwards a definition.
+// GetDomain extracts the domain of the given error, or NoDomain if
+// the error's cause does not have a domain annotation.
 func GetDomain(err error) Domain { return domains.GetDomain(err) }

errbase/format_error.go

@@ -36,6 +36,8 @@ import (
 )
 
 // FormatError formats an error according to s and verb.
+// This is a helper meant for use when implementing the fmt.Formatter
+// interface on custom error objects.
 //
 // If the error implements errors.Formatter, FormatError calls its
 // FormatError method of f with an errors.Printer configured according

errbase_api.go

@@ -21,90 +21,159 @@ import (
 	"github.com/cockroachdb/errors/errbase"
 )
 
-// UnwrapOnce forwards a definition.
+// UnwrapOnce accesses the direct cause of the error if any, otherwise
+// returns nil.
+//
+// It supports both errors implementing causer (`Cause()` method, from
+// github.com/pkg/errors) and `Wrapper` (`Unwrap()` method, from the
+// Go 2 error proposal).
 func UnwrapOnce(err error) error { return errbase.UnwrapOnce(err) }
 
-// UnwrapAll forwards a definition.
+// UnwrapAll accesses the root cause object of the error.
+// If the error has no cause (leaf error), it is returned directly.
 func UnwrapAll(err error) error { return errbase.UnwrapAll(err) }
 
-// EncodedError forwards a definition.
+// EncodedError is the type of an encoded (and protobuf-encodable) error.
 type EncodedError = errbase.EncodedError
 
-// EncodeError forwards a definition.
+// EncodeError encodes an error.
 func EncodeError(ctx context.Context, err error) EncodedError { return errbase.EncodeError(ctx, err) }
 
-// DecodeError forwards a definition.
+// DecodeError decodes an error.
 func DecodeError(ctx context.Context, enc EncodedError) error { return errbase.DecodeError(ctx, enc) }
 
-// SafeDetailer forwards a definition.
+// SafeDetailer is an interface that can be implemented by errors that
+// can provide PII-free additional strings suitable for reporting or
+// telemetry.
 type SafeDetailer = errbase.SafeDetailer
 
-// GetAllSafeDetails forwards a definition.
+// GetAllSafeDetails collects the safe details from the given error object
+// and all its causes.
+// The details are collected from outermost to innermost level of cause.
 func GetAllSafeDetails(err error) []SafeDetailPayload { return errbase.GetAllSafeDetails(err) }
 
-// GetSafeDetails forwards a definition.
+// GetSafeDetails collects the safe details from the given error
+// object. If it is a wrapper, only the details from the wrapper are
+// returned.
 func GetSafeDetails(err error) (payload SafeDetailPayload) { return errbase.GetSafeDetails(err) }
 
-// SafeDetailPayload forwards a definition.
+// SafeDetailPayload captures the safe strings for one
+// level of wrapping.
 type SafeDetailPayload = errbase.SafeDetailPayload
 
-// RegisterLeafDecoder forwards a definition.
+// RegisterLeafDecoder can be used to register new leaf error types to
+// the library. Registered types will be decoded using their own
+// Go type when an error is decoded. Wrappers that have not been
+// registered will be decoded using the opaqueLeaf type.
+//
+// Note: if the error type has been migrated from a previous location
+// or a different type, ensure that RegisterTypeMigration() was called
+// prior to RegisterLeafDecoder().
 func RegisterLeafDecoder(typeName TypeKey, decoder LeafDecoder) {
 	errbase.RegisterLeafDecoder(typeName, decoder)
 }
 
-// TypeKey forwards a definition.
+// TypeKey identifies an error for the purpose of looking up decoders.
+// It is equivalent to the "family name" in ErrorTypeMarker.
 type TypeKey = errbase.TypeKey
 
-// GetTypeKey forwards a definition.
+// GetTypeKey retrieve the type key for a given error object. This
+// is meant for use in combination with the Register functions.
 func GetTypeKey(err error) TypeKey { return errbase.GetTypeKey(err) }
 
-// LeafDecoder forwards a definition.
+// LeafDecoder is to be provided (via RegisterLeafDecoder above)
+// by additional wrapper types not yet known to this library.
+// A nil return indicates that decoding was not successful.
 type LeafDecoder = errbase.LeafDecoder
 
-// RegisterWrapperDecoder forwards a definition.
+// RegisterWrapperDecoder can be used to register new wrapper types to
+// the library. Registered wrappers will be decoded using their own
+// Go type when an error is decoded. Wrappers that have not been
+// registered will be decoded using the opaqueWrapper type.
+//
+// Note: if the error type has been migrated from a previous location
+// or a different type, ensure that RegisterTypeMigration() was called
+// prior to RegisterWrapperDecoder().
 func RegisterWrapperDecoder(typeName TypeKey, decoder WrapperDecoder) {
 	errbase.RegisterWrapperDecoder(typeName, decoder)
 }
 
-// WrapperDecoder forwards a definition.
+// WrapperDecoder is to be provided (via RegisterWrapperDecoder above)
+// by additional wrapper types not yet known to this library.
+// A nil return indicates that decoding was not successful.
 type WrapperDecoder = errbase.WrapperDecoder
 
-// RegisterLeafEncoder forwards a definition.
+// RegisterLeafEncoder can be used to register new leaf error types to
+// the library. Registered types will be encoded using their own
+// Go type when an error is encoded. Wrappers that have not been
+// registered will be encoded using the opaqueLeaf type.
+//
+// Note: if the error type has been migrated from a previous location
+// or a different type, ensure that RegisterTypeMigration() was called
+// prior to RegisterLeafEncoder().
 func RegisterLeafEncoder(typeName TypeKey, encoder LeafEncoder) {
 	errbase.RegisterLeafEncoder(typeName, encoder)
 }
 
-// LeafEncoder forwards a definition.
+// LeafEncoder is to be provided (via RegisterLeafEncoder above)
+// by additional wrapper types not yet known to this library.
 type LeafEncoder = errbase.LeafEncoder
 
-// RegisterWrapperEncoder forwards a definition.
+// RegisterWrapperEncoder can be used to register new wrapper types to
+// the library. Registered wrappers will be encoded using their own
+// Go type when an error is encoded. Wrappers that have not been
+// registered will be encoded using the opaqueWrapper type.
+//
+// Note: if the error type has been migrated from a previous location
+// or a different type, ensure that RegisterTypeMigration() was called
+// prior to RegisterWrapperEncoder().
 func RegisterWrapperEncoder(typeName TypeKey, encoder WrapperEncoder) {
 	errbase.RegisterWrapperEncoder(typeName, encoder)
 }
 
-// WrapperEncoder forwards a definition.
+// WrapperEncoder is to be provided (via RegisterWrapperEncoder above)
+// by additional wrapper types not yet known to this library.
 type WrapperEncoder = errbase.WrapperEncoder
 
-// SetWarningFn forwards a definition.
+// SetWarningFn enables configuration of the warning function.
 func SetWarningFn(fn func(context.Context, string, ...interface{})) { errbase.SetWarningFn(fn) }
 
-// Formatter is provided for compatibility with xerrors.
-// This should probably not be used directly, and
-// SafeFormatter preferred instead.
+// A Formatter formats error messages.
+//
+// NB: Consider implementing SafeFormatter instead. This will ensure
+// that error displays can distinguish bits that are PII-safe.
 type Formatter = errbase.Formatter
 
-// SafeFormatter is like Formatter but supports the separation
-// of safe and unsafe strings.
+// SafeFormatter is implemented by error leaf or wrapper types that want
+// to separate safe and non-safe information when printed out.
+//
+// When multiple errors are chained (e.g. via errors.Wrap), intermediate
+// layers in the error that do not implement SafeError are considered
+// “unsafe”
 type SafeFormatter = errbase.SafeFormatter
 
-// Printer is provided for compatibility with xerrors.
+// A Printer formats error messages.
+//
+// The most common implementation of Printer is the one provided by package fmt
+// during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message
+// typically provide their own implementations.
 type Printer = errbase.Printer
 
-// FormatError can be used to implement the fmt.Formatter interface.
+// FormatError formats an error according to s and verb.
+// This is a helper meant for use when implementing the fmt.Formatter
+// interface on custom error objects.
+//
+// If the error implements errors.Formatter, FormatError calls its
+// FormatError method of f with an errors.Printer configured according
+// to s and verb, and writes the result to s.
+//
+// Otherwise, if it is a wrapper, FormatError prints out its error prefix,
+// then recurses on its cause.
+//
+// Otherwise, its Error() text is printed.
 func FormatError(err error, s fmt.State, verb rune) { errbase.FormatError(err, s, verb) }
 
-// Formattable can be used to print an error with enhanced detail
-// printout when the outer layer of wrapping may not be provided by
-// this library.
+// Formattable wraps an error into a fmt.Formatter which
+// will provide "smart" formatting even if the outer layer
+// of the error does not implement the Formatter interface.
 func Formattable(err error) fmt.Formatter { return errbase.Formattable(err) }

errutil/message.go

@@ -18,6 +18,8 @@ import "github.com/cockroachdb/redact"
 
 // WithMessage annotates err with a new message.
 // If err is nil, WithMessage returns nil.
+// The message is considered safe for reporting
+// and is included in Sentry reports.
 func WithMessage(err error, message string) error {
 	if err == nil {
 		return nil
@@ -30,6 +32,8 @@ func WithMessage(err error, message string) error {
 
 // WithMessagef annotates err with the format specifier.
 // If err is nil, WithMessagef returns nil.
+// The message is formatted as per redact.Sprintf,
+// to separate safe and unsafe strings for Sentry reporting.
 func WithMessagef(err error, format string, args ...interface{}) error {
 	if err == nil {
 		return nil