errors: document Is and As methods

Add brief descriptions of why one might implement
an Is or As method.

Fixes #33364.

Change-Id: I81a091bf564c654ddb9ef3997e780451a01efb7a
Reviewed-on: https://go-review.googlesource.com/c/go/+/191338
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/errors/wrap.go b/src/errors/wrap.go
index 240da37c2952eb6589b6d4156c022b918497e4ed..65e6c448538e74dd603c6adc98bda4d7f2cf0cbe 100644 (file)
--- a/src/errors/wrap.go
+++ b/src/errors/wrap.go
@@ -28,6 +28,14 @@ func Unwrap(err error) error {
 //
 // 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.
+//
+// An error type might provide an Is method so it can be treated as equivalent
+// to an existing error. For example, if MyError defines
+//
+//     func (m MyError) Is(target error) bool { return target == os.ErrExist }
+//
+// then Is(MyError{}, os.ErrExist) returns true. See syscall.Errno.Is for
+// an example in the standard library.
 func Is(err, target error) bool {
        if target == nil {
                return err == target
@@ -61,7 +69,10 @@ func Is(err, target error) bool {
 // As(target) returns true. In the latter case, the As method is responsible for
 // setting target.
 //
-// As will panic if target is not a non-nil pointer to either a type that implements
+// An error type might provide an As method so it can be treated as if it were a
+// a different error type.
+//
+// As panics if target is not a non-nil pointer to either a type that implements
 // error, or to any interface type. As returns false if err is nil.
 func As(err error, target interface{}) bool {
        if target == nil {