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: 7a0ec45
GitHub-Pull-Request: #59301
Reviewed-on: https://go-review.googlesource.com/c/go/+/480021
Run-TryBot: Emmanuel Odeke <[email protected]>
Auto-Submit: Emmanuel Odeke <[email protected]>
Run-TryBot: Ian Lance Taylor <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Damien Neil <[email protected]>

Author: dnephin

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 {

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