errors: improve doc
Explain wrapping and how to use Is and As in the package doc.
Explain "chain" in Is and As.
Updates #33364.
Change-Id: Ic06362106dbd129e33dd47e63176ee5355492086
Reviewed-on: https://go-review.googlesource.com/c/go/+/188737
Reviewed-by: Rob Pike <r@golang.org>
diff --git a/src/errors/errors.go b/src/errors/errors.go
index b8a4692..85d4260 100644
--- a/src/errors/errors.go
+++ b/src/errors/errors.go
@@ -3,9 +3,58 @@
// license that can be found in the LICENSE file.
// Package errors implements functions to manipulate errors.
+//
+// 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
+//
+// Unwrap() error
+//
+// If e.Unwrap() returns a non-nil error w, then we say that e wraps w.
+//
+// A simple way to create wrapped errors is to call fmt.Errorf and apply the %w verb
+// to the error argument:
+//
+// fmt.Errorf("... %w ...", ..., err, ...).Unwrap()
+//
+// returns err.
+//
+// Unwrap unpacks wrapped errors. If its argument's type has an
+// Unwrap method, it calls the method once. Otherwise, it returns nil.
+//
+// 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:
+//
+// if errors.Is(err, os.ErrExist)
+//
+// is preferable to
+//
+// if err == os.ErrExist
+//
+// because the former will succeed if err wraps os.ErrExist.
+//
+// As unwraps its first argument sequentially 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
+//
+// var perr *os.PathError
+// if errors.As(err, &perr) {
+// fmt.Println(perr.Path)
+// }
+//
+// is preferable to
+//
+// if perr, ok := err.(*os.PathError); ok {
+// fmt.Println(perr.Path)
+// }
+//
+// because the former will succeed if err wraps an *os.PathError.
package errors
// New returns an error that formats as the given text.
+// Each call to New returns a distinct error value even if the text is identical.
func New(text string) error {
return &errorString{text}
}
diff --git a/src/errors/wrap.go b/src/errors/wrap.go
index 666d1ff..240da37 100644
--- a/src/errors/wrap.go
+++ b/src/errors/wrap.go
@@ -23,6 +23,9 @@
// Is reports whether any error in err's chain matches target.
//
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
// An error is considered to match a target if it is equal to that target or if
// it implements a method Is(error) bool such that Is(target) returns true.
func Is(err, target error) bool {
@@ -50,6 +53,9 @@
// As finds the first error in err's chain that matches target, and if so, sets
// target to that error value and returns true.
//
+// The chain consists of err itself followed by the sequence of errors obtained by
+// repeatedly calling Unwrap.
+//
// An error matches target if the error's concrete value is assignable to the value
// pointed to by target, or if the error has a method As(interface{}) bool such that
// As(target) returns true. In the latter case, the As method is responsible for
