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")