From: Jonathan Amsterdam Date: Thu, 22 Aug 2019 16:29:29 +0000 (-0400) Subject: errors: document Is and As methods X-Git-Tag: go1.14beta1~1356 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=fc4663d56f2ac550c0deca6ed0261d894be49465;p=gostls13.git 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 Reviewed-by: Andrew Bonventre Run-TryBot: Jonathan Amsterdam TryBot-Result: Gobot Gobot --- diff --git a/src/errors/wrap.go b/src/errors/wrap.go index 240da37c29..65e6c44853 100644 --- 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 {