doc tweaks

errors.go

@@ -14,13 +14,18 @@
 // Adding context to an error
 //
 // The errors.Wrap function returns a new error that adds context to the
-// original error. For example
+// original error by recording a stack trace at the point Wrap is called,
+// and the supplied message. For example
 //
 //     _, err := ioutil.ReadAll(r)
 //     if err != nil {
 //             return errors.Wrap(err, "read failed")
 //     }
 //
+// If additional control is required the errors.WithStack and errors.WithMessage
+// functions destructure errors.Wrap into its component operations of annotating
+// an error with a stack trace and an a message, respectively.
+//
 // Retrieving the cause of an error
 //
 // Using errors.Wrap constructs a stack of errors, adding context to the
@@ -169,7 +174,8 @@ func (w *withStack) Format(s fmt.State, verb rune) {
 	}
 }
 
-// Wrap returns an error annotating err with message.
+// Wrap returns an error annotating err with a stack trace
+// at the point Wrap is called, and the supplied message.
 // If err is nil, Wrap returns nil.
 func Wrap(err error, message string) error {
 	if err == nil {
@@ -185,7 +191,8 @@ func Wrap(err error, message string) error {
 	}
 }
 
-// Wrapf returns an error annotating err with the format specifier.
+// Wrapf returns an error annotating err with a stack trace
+// at the point Wrapf is call, and the format specifier.
 // If err is nil, Wrapf returns nil.
 func Wrapf(err error, format string, args ...interface{}) error {
 	if err == nil {