errors: improve the godoc for Join and Unwrap

Document that errors returned by Join always implement Unwrap []error.

Explicitly state that Unwrap does not unwrap errors
with an Unwrap() []error method.

Change-Id: Id610345dcf43ca54a9dde157e56c5815c5112073
GitHub-Last-Rev: 7a0ec450bd0b2b38eecb5b94eaec485f4a6debbd
GitHub-Pull-Request: golang/go#59301
Reviewed-on: https://go-review.googlesource.com/c/go/+/480021
Run-TryBot: Emmanuel Odeke <emmanuel@orijtech.com>
Auto-Submit: Emmanuel Odeke <emmanuel@orijtech.com>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>

diff --git a/src/errors/join.go b/src/errors/join.go
index 329082a5e3b481dd195398750e6bec41346930f6..1c486d591e35bf19e20efabc9ac48f68864e603d 100644 (file)
--- a/src/errors/join.go
+++ b/src/errors/join.go
@@ -10,6 +10,8 @@ package errors
 // The error formats as the concatenation of the strings obtained
 // by calling the Error method of each element of errs, with a newline
 // between each string.
+//
+// A non-nil error returned by Join implements the Unwrap() []error method.
 func Join(errs ...error) error {
        n := 0
        for _, err := range errs {

diff --git a/src/errors/wrap.go b/src/errors/wrap.go
index a719655b10dbbf2de2f910fbf12c715000be2951..1f54b66e5cbf6770cda691f8670a1823732761ea 100644 (file)
--- a/src/errors/wrap.go
+++ b/src/errors/wrap.go
@@ -12,7 +12,8 @@ import (
 // type contains an Unwrap method returning error.
 // Otherwise, Unwrap returns nil.
 //
-// Unwrap returns nil if the Unwrap method returns []error.
+// Unwrap only calls a method of the form "Unwrap() error".
+// In particular Unwrap does not unwrap errors returned by [Join].
 func Unwrap(err error) error {
        u, ok := err.(interface {
                Unwrap() error