diff options
Diffstat (limited to 'src/errors/errors.go')
| -rw-r--r-- | src/errors/errors.go | 31 |
1 files changed, 17 insertions, 14 deletions
diff --git a/src/errors/errors.go b/src/errors/errors.go index f2fabacd4e..8436f812a6 100644 --- a/src/errors/errors.go +++ b/src/errors/errors.go @@ -6,26 +6,29 @@ // // The New function creates errors whose only content is a text message. // -// The Unwrap, Is and As functions work on errors that may wrap other errors. -// An error wraps another error if its type has the method +// An error e wraps another error if e's type has one of the methods // // Unwrap() error +// Unwrap() []error // -// If e.Unwrap() returns a non-nil error w, then we say that e wraps w. +// If e.Unwrap() returns a non-nil error w or a slice containing w, +// then we say that e wraps w. A nil error returned from e.Unwrap() +// indicates that e does not wrap any error. It is invalid for an +// Unwrap method to return an []error containing a nil error value. // -// Unwrap unpacks wrapped errors. If its argument's type has an -// Unwrap method, it calls the method once. Otherwise, it returns nil. +// An easy way to create wrapped errors is to call fmt.Errorf and apply +// the %w verb to the error argument: // -// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb -// to the error argument: +// wrapsErr := fmt.Errorf("... %w ...", ..., err, ...) // -// errors.Unwrap(fmt.Errorf("... %w ...", ..., err, ...)) +// Successive unwrapping of an error creates a tree. The Is and As +// functions inspect an error's tree by examining first the error +// itself followed by the tree of each of its children in turn +// (pre-order, depth-first traversal). // -// returns err. -// -// Is unwraps its first argument sequentially looking for an error that matches the -// second. It reports whether it finds a match. It should be used in preference to -// simple equality checks: +// Is examines the tree of its first argument looking for an error that +// matches the second. It reports whether it finds a match. It should be +// used in preference to simple equality checks: // // if errors.Is(err, fs.ErrExist) // @@ -35,7 +38,7 @@ // // because the former will succeed if err wraps fs.ErrExist. // -// As unwraps its first argument sequentially looking for an error that can be +// As examines the tree of its first argument looking for an error that can be // assigned to its second argument, which must be a pointer. If it succeeds, it // performs the assignment and returns true. Otherwise, it returns false. The form // |