errors: clarify that Join doesn't extend already-joined errors

Updates the documentation for Join to explain that it does not append to an existing joinError (i.e. the result of calling Join), and if one of the errors is a joinError, it will be wrapped again. See #60209

It also adds a test to provide an example of said behavior, as well as formalizing it in the API's contract.

Author: ItalyPaleAle

src/errors/join.go

@@ -12,6 +12,11 @@ package errors
 // between each string.
 //
 // A non-nil error returned by Join implements the Unwrap() []error method.
+//
+// Calling Join on an error that was previously returned by Join wraps
+// the error again. Consequently, calling Unwrap() []error on the result
+// of Join(Join(err1, err2), err3) returns a slice with 2 items, of which
+// the first one implements Unwrap() []error too.
 func Join(errs ...error) error {
 	n := 0
 	for _, err := range errs {

src/errors/join_test.go

@@ -70,3 +70,48 @@ func TestJoinErrorMethod(t *testing.T) {
 		}
 	}
 }
+
+func TestJoinWithJoinedError(t *testing.T) {
+	err1 := errors.New("err1")
+	err2 := errors.New("err2")
+
+	var err error
+	err = errors.Join(err, err1)
+	if err == nil {
+		t.Fatal("errors.Join(err, err1) = nil, want non-nil")
+	}
+
+	gotErrs := err.(interface{ Unwrap() []error }).Unwrap()
+	if len(gotErrs) != 1 {
+		t.Fatalf("errors.Join(err, err1) returns errors with len=%v, want len==1", len(gotErrs))
+	}
+
+	err = errors.Join(err, err2)
+	if err == nil {
+		t.Fatal("errors.Join(err, err2) = nil, want non-nil")
+	}
+
+	gotErrs = err.(interface{ Unwrap() []error }).Unwrap()
+	if len(gotErrs) != 2 {
+		t.Fatalf("errors.Join(err, err2) returns errors with len=%v, want len==2", len(gotErrs))
+	}
+
+	// Wraps the error again, so the resulting joined error will have len==1
+	err = errors.Join(err, nil)
+	if err == nil {
+		t.Fatal("errors.Join(err, nil) = nil, want non-nil")
+	}
+
+	gotErrs = err.(interface{ Unwrap() []error }).Unwrap()
+	if len(gotErrs) != 1 {
+		t.Fatalf("errors.Join(err, nil) returns errors with len=%v, want len==1", len(gotErrs))
+	}
+
+	if err.Error() != "err1\nerr2" {
+		t.Errorf("Join(err, nil).Error() = %q; want %q", err.Error(), "err1\nerr2")
+	}
+
+	if _, ok := gotErrs[0].(interface{ Unwrap() []error }); !ok {
+		t.Error("first error returned by errors.Join(err, nil) is not a joined error")
+	}
+}