xerrors: add and modify documentation
Also split examples into separate files so their full contents appear
in the godoc.
Change-Id: I1c6432687262a59f9b0890d60d23de2e6022b08e
Reviewed-on: https://go-review.googlesource.com/c/159657
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
diff --git a/xerrors/adaptor.go b/xerrors/adaptor.go
index 038b10e..83a7945 100644
--- a/xerrors/adaptor.go
+++ b/xerrors/adaptor.go
@@ -12,8 +12,8 @@
"strconv"
)
-// FormatError calls the FormatError method of err with a errors.Printer
-// configured according to s and verb and writes the result to s.
+// FormatError calls the FormatError method of f with an errors.Printer
+// configured according to s and verb, and writes the result to s.
func FormatError(f Formatter, s fmt.State, verb rune) {
// Assuming this function is only called from the Format method, and given
// that FormatError takes precedence over Format, it cannot be called from
diff --git a/xerrors/doc.go b/xerrors/doc.go
new file mode 100644
index 0000000..d77f9f0
--- /dev/null
+++ b/xerrors/doc.go
@@ -0,0 +1,27 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package xerrors implements functions to manipulate errors.
+//
+// This package supports transitioning to the Go 2 proposal for error values:
+// https://golang.org/design/29934-error-values
+//
+// This is an EXPERIMENTAL package, and may change in arbitrary ways without notice.
+//
+// Most of the functions and types in this package will be incorporated into the
+// standard library's errors package in Go 1.13; the behavior of this package's
+// Errorf function will be incorporated into the standard library's fmt.Errorf. Use
+// this package to get equivalent behavior in all supported Go versions. For example,
+// create errors using
+//
+// xerrors.New("write failed")
+//
+// or
+//
+// xerrors.Errorf("while reading: %v", err)
+//
+// If you want your error type to participate in the new formatting implementation
+// for %v and %+v, provide it with a Format method that calls xerrors.FormatError, as
+// shown in the example for FormatError.
+package xerrors // TODO import "golang.org/x/xerrors"
diff --git a/xerrors/errors.go b/xerrors/errors.go
index 61943db..0a812bd 100644
--- a/xerrors/errors.go
+++ b/xerrors/errors.go
@@ -2,12 +2,6 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
-// Package errors implements functions to manipulate errors.
-//
-// This package implements the Go 2 draft designs for error inspection and printing:
-// https://go.googlesource.com/proposal/+/master/design/go2draft.md
-//
-// This is an EXPERIMENTAL package, and may change in arbitrary ways without notice.
package xerrors
// errorString is a trivial implementation of error.
diff --git a/xerrors/example_As_test.go b/xerrors/example_As_test.go
new file mode 100644
index 0000000..b5e95b2
--- /dev/null
+++ b/xerrors/example_As_test.go
@@ -0,0 +1,25 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package xerrors_test
+
+import (
+ "fmt"
+ "os"
+
+ "golang.org/x/exp/xerrors"
+)
+
+func ExampleAs() {
+ _, err := os.Open("non-existing")
+ if err != nil {
+ var pathError *os.PathError
+ if xerrors.As(err, &pathError) {
+ fmt.Println("Failed at path:", pathError.Path)
+ }
+ }
+
+ // Output:
+ // Failed at path: non-existing
+}
diff --git a/xerrors/example_FormatError_test.go b/xerrors/example_FormatError_test.go
new file mode 100644
index 0000000..a9bf7cd
--- /dev/null
+++ b/xerrors/example_FormatError_test.go
@@ -0,0 +1,39 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package xerrors_test
+
+import (
+ "fmt"
+
+ "golang.org/x/exp/xerrors"
+)
+
+type MyError2 struct {
+ Message string
+ frame xerrors.Frame
+}
+
+func (m *MyError2) Error() string {
+ return m.Message
+}
+
+func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter
+ xerrors.FormatError(m, f, c)
+}
+
+func (m *MyError2) FormatError(p xerrors.Printer) error { // implements xerrors.Formatter
+ p.Print(m.Message)
+ if p.Detail() {
+ m.frame.Format(p)
+ }
+ return nil
+}
+
+func ExampleFormatError() {
+ err := &MyError2{Message: "oops", frame: xerrors.Caller(1)}
+ fmt.Printf("%v\n", err)
+ fmt.Println()
+ fmt.Printf("%+v\n", err)
+}
diff --git a/xerrors/example_test.go b/xerrors/example_test.go
index f07d092..107f80c 100644
--- a/xerrors/example_test.go
+++ b/xerrors/example_test.go
@@ -6,10 +6,7 @@
import (
"fmt"
- "os"
"time"
-
- "golang.org/x/exp/xerrors"
)
// MyError is an error implementation that includes a time and message.
@@ -35,16 +32,3 @@
}
// Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away
}
-
-func ExampleAs() {
- _, err := os.Open("non-existing")
- if err != nil {
- var pathError *os.PathError
- if xerrors.As(err, &pathError) {
- fmt.Println("Failed at path:", pathError.Path)
- }
- }
-
- // Output:
- // Failed at path: non-existing
-}
diff --git a/xerrors/format.go b/xerrors/format.go
index 7af63fb..1bc9c26 100644
--- a/xerrors/format.go
+++ b/xerrors/format.go
@@ -16,7 +16,7 @@
// A Printer formats error messages.
//
// The most common implementation of Printer is the one provided by package fmt
-// during Printf. Localization packages such as golang.org/x/text/message
+// during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message
// typically provide their own implementations.
type Printer interface {
// Print appends args to the message output.
diff --git a/xerrors/frame.go b/xerrors/frame.go
index ae7ee9d..0de628e 100644
--- a/xerrors/frame.go
+++ b/xerrors/frame.go
@@ -41,8 +41,8 @@
}
// Format prints the stack as error detail.
-// It should be called from an error's Format implementation,
-// before printing any other error detail.
+// It should be called from an error's Format implementation
+// after printing any other error detail.
func (f Frame) Format(p Printer) {
if p.Detail() {
function, file, line := f.location()
diff --git a/xerrors/wrap.go b/xerrors/wrap.go
index 4024b08..eee732b 100644
--- a/xerrors/wrap.go
+++ b/xerrors/wrap.go
@@ -33,8 +33,8 @@
return nil
}
-// Unwrap returns the next error in err's chain.
-// If there is no next error, Unwrap returns nil.
+// Unwrap returns the result of calling the Unwrap method on err, if err implements
+// Unwrap. Otherwise, Unwrap returns nil.
func Unwrap(err error) error {
u, ok := err.(Wrapper)
if !ok {
@@ -46,7 +46,7 @@
// Is reports whether any error in err's chain matches target.
//
// An error is considered to match a target if it is equal to that target or if
-// it implements an Is method such that Is(target) returns true.
+// it implements a method Is(error) bool such that Is(target) returns true.
func Is(err, target error) bool {
if target == nil {
return err == target
@@ -67,13 +67,13 @@
}
}
-// As finds the first error in err's chain that matches a type to which target
-// points, and if so, sets the target to its value and reports success. An error
-// matches a type if it is of the same type, or if it has an As method such that
-// As(target) returns true. As will panic if target is nil or not a pointer.
+// As finds the first error in err's chain that matches the type to which target
+// points, and if so, sets the target to its value and and returns true. An error
+// matches a type if it is of the same type, or if it has a method As(interface{}) bool
+// such that As(target) returns true. As will panic if target is nil or not a pointer.
//
-// The As method should set the target to its value and report success if err
-// matches the type to which target points and report success.
+// The As method should set the target to its value and return true if err
+// matches the type to which target points.
func As(err error, target interface{}) bool {
if target == nil {
panic("errors: target cannot be nil")
