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>

2 files changed, 55 insertions, 0 deletions

diff --git a/src/errors/errors.go b/src/errors/errors.go
index b8a46921be..85d4260762 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 666d1ff207..240da37c29 100644
--- a/src/errors/wrap.go
+++ b/src/errors/wrap.go
@@ -23,6 +23,9 @@ func Unwrap(err error) error {
 
 // 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 @@ func Is(err, target error) bool {
 // 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