[chore] Reorganize documentation regarding consumer errors for receiver

consumer/consumererror/doc.go

@@ -3,5 +3,21 @@
 
 // Package consumererror provides wrappers to easily classify errors. This allows
 // appropriate action by error handlers without the need to know each individual
-// error type/instance.
+// error type/instance. These errors are returned by the Consume*() functions of
+// the consumer interfaces.
+//
+// # Error handling
+//
+// The consumererror package provides a way to classify errors into two categories: Permanent and
+// NonPermanent. The Permanent errors are those that are not expected to be resolved by retrying the
+// same data.
+//
+// If the error is Permanent, then the Consume*() call should not be retried with the same data.
+// This typically happens when the data cannot be serialized by the exporter that is attached to the
+// pipeline or when the destination refuses the data because it cannot decode it.
+//
+// If the error is non-Permanent then the Consume*() call should be retried with the same data. This
+// may be done by the component itself, however typically it is done by the original sender, after
+// the receiver in the pipeline returns a response to the sender indicating that the Collector is
+// currently overloaded and the request must be retried.
 package consumererror // import "go.opentelemetry.io/collector/consumer/consumererror"

receiver/doc.go

@@ -1,32 +1,21 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-// Package receiver defines components that allows the collector to receive metrics, traces and logs.
+// Package receiver defines components that allow the Collector to receive metrics, traces and logs.
 //
-// Receiver receives data from a source (either from a remote source via network
+// A receiver receives data from a source (either from a remote source via network
 // or scrapes from a local host) and pushes the data to the pipelines it is attached
 // to by calling the nextConsumer.Consume*() function.
 //
 // # Error Handling
 //
-// The nextConsumer.Consume*() function may return an error to indicate that the data
-// was not accepted. There are 2 types of possible errors: Permanent and non-Permanent.
-// The receiver must check the type of the error using IsPermanent() helper.
-//
-// If the error is Permanent, then the nextConsumer.Consume*() call should not be
-// retried with the same data. This typically happens when the data cannot be
-// serialized by the exporter that is attached to the pipeline or when the destination
-// refuses the data because it cannot decode it. The receiver must indicate to
-// the source from which it received the data that the received data was bad, if the
-// receiving protocol allows to do that. In case of OTLP/HTTP for example, this means
-// that HTTP 400 response is returned to the sender.
-//
-// If the error is non-Permanent then the nextConsumer.Consume*() call should be retried
-// with the same data. This may be done by the receiver itself, however typically it is
-// done by the original sender, after the receiver returns a response to the sender
-// indicating that the Collector is currently overloaded and the request must be
-// retried. In case of OTLP/HTTP for example, this means that HTTP 429 or 503 response
-// is returned.
+// The nextConsumer.Consume*() function may return an error to indicate that the data was not
+// accepted. This error should be handled as documented in the consumererror package.
+//
+// Depending on the error type, the receiver must indicate to the source from which it received the
+// data the type of error in a protocol-dependent way, if that is supported by the receiving protocol.
+// For example, a receiver for the OTLP/HTTP protocol would use the HTTP status codes as defined in
+// the OTLP specification.
 //
 // # Acknowledgment and Checkpointing
 //