Edit type/func documentation in the consumer package

CHANGELOG.md

@@ -6,6 +6,10 @@
 
 - Remove unused logstest package (#3222)
 
+## 💡 Enhancements 💡
+
+- Improve documentation of consumer package and subpackages (#3269)
+
 ## v0.27.0 Beta
 
 ## 🛑 Breaking changes 🛑

consumer/consumererror/permanent.go

@@ -25,7 +25,7 @@ type permanent struct {
 	err error
 }
 
-// Permanent wraps an error to indicate that it is a permanent error, i.e.: an
+// Permanent wraps an error to indicate that it is a permanent error, i.e. an
 // error that will be always returned if its source receives the same inputs.
 func Permanent(err error) error {
 	return permanent{err: err}
@@ -40,7 +40,7 @@ func (p permanent) Unwrap() error {
 	return p.err
 }
 
-// IsPermanent checks if an error was wrapped with the Permanent function, that
+// IsPermanent checks if an error was wrapped with the Permanent function, which
 // is used to indicate that a given error will always be returned in the case
 // that its sources receives the same input.
 func IsPermanent(err error) bool {

consumer/consumererror/signalerrors.go

@@ -35,7 +35,7 @@ func NewTraces(err error, failed pdata.Traces) error {
 	}
 }
 
-// AsTraces finds the first error in err's chain that can be assigned to target. If such an error is found
+// AsTraces finds the first error in err's chain that can be assigned to target. If such an error is found,
 // it is assigned to target and true is returned, otherwise false is returned.
 func AsTraces(err error, target *Traces) bool {
 	if err == nil {
@@ -69,7 +69,7 @@ func NewLogs(err error, failed pdata.Logs) error {
 	}
 }
 
-// AsLogs finds the first error in err's chain that can be assigned to target. If such an error is found
+// AsLogs finds the first error in err's chain that can be assigned to target. If such an error is found,
 // it is assigned to target and true is returned, otherwise false is returned.
 func AsLogs(err error, target *Logs) bool {
 	if err == nil {
@@ -103,7 +103,7 @@ func NewMetrics(err error, failed pdata.Metrics) error {
 	}
 }
 
-// AsMetrics finds the first error in err's chain that can be assigned to target. If such an error is found
+// AsMetrics finds the first error in err's chain that can be assigned to target. If such an error is found,
 // it is assigned to target and true is returned, otherwise false is returned.
 func AsMetrics(err error, target *Metrics) bool {
 	if err == nil {

consumer/consumerhelper/common.go

@@ -26,10 +26,10 @@ type baseConsumer struct {
 	capabilities consumer.Capabilities
 }
 
-// Option apply changes to internalOptions.
+// Option applies changes to internalOptions.
 type Option func(*baseConsumer)
 
-// WithCapabilities overrides the default GetCapabilities function for an processor.
+// WithCapabilities overrides the default GetCapabilities function for a processor.
 // The default GetCapabilities function returns mutable capabilities.
 func WithCapabilities(capabilities consumer.Capabilities) Option {
 	return func(o *baseConsumer) {

consumer/consumertest/base_consumer.go

@@ -20,6 +20,7 @@ import (
 
 type nonMutatingConsumer struct{}
 
+// Capabilities returns the base consumer capabilities.
 func (bc nonMutatingConsumer) Capabilities() consumer.Capabilities {
 	return consumer.Capabilities{MutatesData: false}
 }

consumer/consumertest/consumer.go

@@ -22,9 +22,9 @@ import (
 )
 
 // Consumer is a convenience interface that implements all consumer interfaces.
-// It has a private function on it to forbid external users to implement it,
-// to allow us to add extra functions without breaking compatibility because
-// nobody else implements this interface.
+// It has a private function on it to forbid external users from implementing it
+// and, as a result, to allow us to add extra functions without breaking
+// compatibility.
 type Consumer interface {
 	// Capabilities to implement the base consumer functionality.
 	Capabilities() consumer.Capabilities

consumer/consumertest/err.go

@@ -39,7 +39,7 @@ func (er *errConsumer) ConsumeLogs(context.Context, pdata.Logs) error {
 	return er.err
 }
 
-// NewErr returns a Consumer that just drops all received data and returns no error.
+// NewErr returns a Consumer that just drops all received data and holds the input error.
 func NewErr(err error) Consumer {
 	return &errConsumer{err: err}
 }

consumer/consumertest/sink.go

@@ -54,7 +54,7 @@ func (ste *TracesSink) AllTraces() []pdata.Traces {
 	return copyTraces
 }
 
-// SpansCount return the number of spans sent to this sink.
+// SpansCount returns the number of spans sent to this sink.
 func (ste *TracesSink) SpansCount() int {
 	ste.mu.Lock()
 	defer ste.mu.Unlock()
@@ -102,7 +102,7 @@ func (sme *MetricsSink) AllMetrics() []pdata.Metrics {
 	return copyMetrics
 }
 
-// MetricsCount return the number of metrics stored by this sink since last Reset.
+// MetricsCount returns the number of metrics stored by this sink since last Reset.
 func (sme *MetricsSink) MetricsCount() int {
 	sme.mu.Lock()
 	defer sme.mu.Unlock()
@@ -150,7 +150,7 @@ func (sle *LogsSink) AllLogs() []pdata.Logs {
 	return copyLogs
 }
 
-// LogRecordsCount return the number of log records stored by this sink since last Reset.
+// LogRecordsCount returns the number of log records stored by this sink since last Reset.
 func (sle *LogsSink) LogRecordsCount() int {
 	sle.mu.Lock()
 	defer sle.mu.Unlock()

consumer/pdata/common.go

@@ -36,6 +36,7 @@ const (
 	AttributeValueTypeArray
 )
 
+// String returns the string representation of the AttributeValueType.
 func (avt AttributeValueType) String() string {
 	switch avt {
 	case AttributeValueTypeNull:
@@ -65,12 +66,12 @@ func (avt AttributeValueType) String() string {
 //
 //   function f1(val AttributeValue) { val.SetIntVal(234) }
 //   function f2() {
-//   	v := NewAttributeValueString("a string")
-//      f1(v)
-//      _ := v.Type() // this will return AttributeValueTypeInt
+//       v := NewAttributeValueString("a string")
+//       f1(v)
+//       _ := v.Type() // this will return AttributeValueTypeInt
 //   }
 //
-// Important: zero-initialized instance is not valid for use. All AttributeValue functions bellow must
+// Important: zero-initialized instance is not valid for use. All AttributeValue functions below must
 // be called only on instances that are created via NewAttributeValue+ functions.
 type AttributeValue struct {
 	orig *otlpcommon.AnyValue
@@ -362,7 +363,7 @@ func newAttributeMap(orig *[]otlpcommon.KeyValue) AttributeMap {
 // with values from the given map[string]string.
 //
 // Returns the same instance to allow nicer code like:
-// assert.EqualValues(t, NewAttributeMap().InitFromMap(map[string]AttributeValue{...}), actual)
+//   assert.EqualValues(t, NewAttributeMap().InitFromMap(map[string]AttributeValue{...}), actual)
 func (am AttributeMap) InitFromMap(attrMap map[string]AttributeValue) AttributeMap {
 	if len(attrMap) == 0 {
 		*am.orig = []otlpcommon.KeyValue(nil)
@@ -586,7 +587,7 @@ func (am AttributeMap) UpsertBool(k string, v bool) {
 
 // Sort sorts the entries in the AttributeMap so two instances can be compared.
 // Returns the same instance to allow nicer code like:
-// assert.EqualValues(t, expected.Sort(), actual.Sort())
+//   assert.EqualValues(t, expected.Sort(), actual.Sort())
 func (am AttributeMap) Sort() AttributeMap {
 	// Intention is to move the nil values at the end.
 	sort.SliceStable(*am.orig, func(i, j int) bool {
@@ -607,9 +608,9 @@ func (am AttributeMap) Len() int {
 //
 // Example:
 //
-// it := sm.Range(func(k string, v AttributeValue) {
-//   ...
-// })
+//   it := sm.Range(func(k string, v AttributeValue) {
+//       ...
+//   })
 func (am AttributeMap) Range(f func(k string, v AttributeValue) bool) {
 	for i := range *am.orig {
 		kv := &(*am.orig)[i]
@@ -664,7 +665,7 @@ func newStringMap(orig *[]otlpcommon.StringKeyValue) StringMap {
 // with values from the given map[string]string.
 //
 // Returns the same instance to allow nicer code like:
-// assert.EqualValues(t, NewStringMap().InitFromMap(map[string]string{...}), actual)
+//   assert.EqualValues(t, NewStringMap().InitFromMap(map[string]string{...}), actual)
 func (sm StringMap) InitFromMap(attrMap map[string]string) StringMap {
 	if len(attrMap) == 0 {
 		*sm.orig = []otlpcommon.StringKeyValue(nil)
@@ -759,9 +760,9 @@ func (sm StringMap) Len() int {
 //
 // Example:
 //
-// it := sm.Range(func(k string, v StringValue) {
-//   ...
-// })
+//   it := sm.Range(func(k string, v StringValue) {
+//       ...
+//   })
 func (sm StringMap) Range(f func(k string, v string) bool) {
 	for i := range *sm.orig {
 		skv := &(*sm.orig)[i]
@@ -800,7 +801,7 @@ func (sm StringMap) get(k string) (*otlpcommon.StringKeyValue, bool) {
 
 // Sort sorts the entries in the StringMap so two instances can be compared.
 // Returns the same instance to allow nicer code like:
-// assert.EqualValues(t, expected.Sort(), actual.Sort())
+//   assert.EqualValues(t, expected.Sort(), actual.Sort())
 func (sm StringMap) Sort() StringMap {
 	sort.SliceStable(*sm.orig, func(i, j int) bool {
 		// Intention is to move the nil values at the end.

consumer/pdata/doc.go

@@ -13,20 +13,20 @@
 // limitations under the License.
 
 // Package pdata (pipeline data) implements data structures that represent telemetry data in-memory.
-// All data received is converted into this format and travels through the pipeline
-// in this format and that is converted from this format by exporters when sending.
+// All data received is converted into this format, travels through the pipeline
+// in this format, and is converted from this format by exporters when sending.
 //
 // Current implementation primarily uses OTLP ProtoBuf structs as the underlying data
 // structures for many of of the declared structs. We keep a pointer to OTLP protobuf
 // in the "orig" member field. This allows efficient translation to/from OTLP wire
-// protocol. Note that the underlying data structure is kept private so that in the
-// future we are free to make changes to it to make more optimal.
+// protocol. Note that the underlying data structure is kept private so that we are
+// free to make changes to it in the future.
 //
 // Most of internal data structures must be created via New* functions. Zero-initialized
-// structures in most cases are not valid (read comments for each struct to know if it
+// structures, in most cases, are not valid (read comments for each struct to know if that
 // is the case). This is a slight deviation from idiomatic Go to avoid unnecessary
 // pointer checks in dozens of functions which assume the invariant that "orig" member
-// is non-nil. Several structures also provide New*Slice functions that allows to create
+// is non-nil. Several structures also provide New*Slice functions that allow creating
 // more than one instance of the struct more efficiently instead of calling New*
 // repeatedly. Use it where appropriate.
 package pdata