add testable examples and more detailed godoc

Author: braydonk

consumer/consumererror/xconsumererror/partial.go

@@ -28,10 +28,20 @@ func (pe partialError) Failed() int {
 	return pe.failed
 }
 
-// NewPartial creates a new partial error. This is used by consumers
-// to report errors where only a subset of the total items failed
-// to be written, but it is not possible to tell which particular items
-// failed.
+// NewPartial creates a new partial error. This is used to report errors
+// where only a subset of the total items failed to be written, but it
+// is not possible to tell which particular items failed. An example of this
+// would be a backend that can report partial successes, but only communicate
+// the number of failed items without specifying which specific items failed.
+//
+// A partial error wraps a PermanentError; it can be treated as any other permanent
+// error with no changes, meaning that consumers can transition to producing this
+// error when appropriate without breaking any parts of the pipeline that check for
+// permanent errors.
+//
+// In a scenario where the exact items that failed are known and can be retried,
+// it's recommended to use the respective signal error ([consumererror.Logs],
+// [consumererror.Metrics], or [consumererror.Traces]).
 func NewPartial(err error, failed int) error {
 	return consumererror.NewPermanent(partialError{
 		inner:  err,
@@ -40,7 +50,9 @@ func NewPartial(err error, failed int) error {
 }
 
 // AsPartial checks if an error was wrapped with the NewPartial function,
-// or if it contains one such error in its Unwrap() tree.
+// or if it contains one such error in its Unwrap() tree. The resulting
+// error has a method Failed() that can be used to retrieve the count of
+// failed items from the error.
 func AsPartial(err error) (partialError, bool) {
 	var pe partialError
 	ok := errors.As(err, &pe)

consumer/consumererror/xconsumererror/partial_test.go

@@ -1,23 +1,58 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-package xconsumererror
+package xconsumererror_test
 
 import (
 	"errors"
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"go.opentelemetry.io/collector/consumer/consumererror"
+	"go.opentelemetry.io/collector/consumer/consumererror/xconsumererror"
 )
 
 func TestPartial(t *testing.T) {
 	internalErr := errors.New("some points failed")
-	err := NewPartial(internalErr, 5)
+	err := xconsumererror.NewPartial(internalErr, 5)
 	assert.True(t, consumererror.IsPermanent(err))
-	partialErr, ok := AsPartial(err)
+	partialErr, ok := xconsumererror.AsPartial(err)
 	assert.True(t, ok)
 	assert.Equal(t, 5, partialErr.Failed())
 	assert.Equal(t, internalErr, partialErr.Unwrap())
 	assert.Equal(t, internalErr.Error(), partialErr.Error())
 }
+
+func ExampleNewPartial() {
+	// Produce a partial error.
+	failedItems := 5
+	consumptionErr := errors.New("some points failed to be written")
+	err := xconsumererror.NewPartial(consumptionErr, failedItems)
+	fmt.Println(err)
+
+	// Output: "Permanent error: some points failed to be written"
+}
+
+func ExampleAsPartial() {
+	// Produce a partial error.
+	partialErr := xconsumererror.NewPartial(errors.New("some points failed to be written"), 10)
+
+	// The result of `xconsumererror.AsPartial` has a method `Failed`
+	// which can be used to retrieve the failed item count.
+	if err, ok := xconsumererror.AsPartial(partialErr); ok {
+		fmt.Println(err.Failed())
+	}
+
+	// Output: 10
+}
+
+func ExampleAsPartial_second() {
+	// Produce a partial error.
+	partialErr := xconsumererror.NewPartial(errors.New("some points failed to be written"), 10)
+
+	// Partial errors wrap a Permanent error.
+	fmt.Println(consumererror.IsPermanent(partialErr))
+
+	// Output: true
+}