Edit type/func documentation in the consumer package (#3269)

* Edited grammar of pdata doc.go

* Added missing word

* Fixed typos in pdata/common.go

* Added missing String method docs

This fix makes the pdata folder consistent in documenting the String methods.

* Fixed spacing in doc example

* Fixed spacing issues in multiple examples

This issue was causing many example snippets to show up incorrectly on the godoc

* Fixed spacing issue on Range example

* Fixed spacing in At example

* Fixed more spacing errors in examples

* Fixed error in ResourceMetrics header describing InstrumentationLibraryMetrics

* Fixed another header referencing wrong method

* Added documentation for pdata.Resource

* Updated outdated links to Span OTLP definition

* Cleaned up wording in SpanStatus doc

* Fixed more spacing errors in examples

* Fixed typos in type docs

* Cleaned up formatting in consumererror

* Cleaned up consumerhelper doc typos

* Updated docs in consumertest

- Fixed wrong description of NewErr
- Added doc for Capabilities method

* Update CHANGELOG.md

* Fixed formatting errors in cmd/pdatagen

Changing here will ensure that the changes to consumer/pdata/generated_* files will persist after running `go run cmd/pdatagen/main.go`.

* Removed unused imports

* Update CHANGELOG.md

* Fixed generated code lint failures

* Revert changes in pdatagen and pdata/generated

* Update NewErr docstring

For func defined in consumer/consumertest/err.go

Co-authored-by: Tigran Najaryan <[email protected]>

* Updated docstring for TraceState

Renamed "message" to "string"

Co-authored-by: Tigran Najaryan <[email protected]>

CHANGELOG.md

@@ -37,6 +37,7 @@
 ## 💡 Enhancements 💡
 
 - Add `doc.go` files to the consumer package and its subpackages (#3270)
+- Improve documentation of consumer package and subpackages (#3269, #3361)
 - Automate triggering of doc-update on release (#3234)
 - Enable Dependabot for Github Actions (#3312)
 - Remove the proto dependency in `goldendataset` for traces (#3322)

consumer/consumererror/permanent.go

@@ -22,7 +22,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}
@@ -37,7 +37,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 returns the specified error to Consume* callers.
 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 the 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

consumer/pdata/logs.go

@@ -135,4 +135,5 @@ const (
 	SeverityNumberFATAL4    = SeverityNumber(otlplogs.SeverityNumber_SEVERITY_NUMBER_FATAL4)
 )
 
+// String returns the string representation of the SeverityNumber.
 func (sn SeverityNumber) String() string { return otlplogs.SeverityNumber(sn).String() }

consumer/pdata/metrics.go

@@ -38,10 +38,10 @@ func (at AggregationTemporality) String() string {
 	return otlpmetrics.AggregationTemporality(at).String()
 }
 
-// Metrics is an opaque interface that allows transition to the new internal Metrics data, but also facilitate the
-// transition to the new components especially for traces.
+// Metrics is an opaque interface that allows transition to the new internal Metrics data, but also facilitates the
+// transition to the new components, especially for traces.
 //
-// Outside of the core repository the metrics pipeline cannot be converted to the new model since data.MetricData is
+// Outside of the core repository, the metrics pipeline cannot be converted to the new model since data.MetricData is
 // part of the internal package.
 type Metrics struct {
 	orig *otlpcollectormetrics.ExportMetricsServiceRequest
@@ -166,6 +166,7 @@ const (
 	MetricDataTypeSummary
 )
 
+// String returns the string representation of the MetricDataType.
 func (mdt MetricDataType) String() string {
 	switch mdt {
 	case MetricDataTypeNone:

consumer/pdata/traces.go

@@ -97,7 +97,7 @@ func (td Traces) ResourceSpans() ResourceSpansSlice {
 	return newResourceSpansSlice(&td.orig.ResourceSpans)
 }
 
-// TraceState in w3c-trace-context format: https://www.w3.org/TR/trace-context/#tracestate-header
+// TraceState is a string representing the tracestate in w3c-trace-context format: https://www.w3.org/TR/trace-context/#tracestate-header
 type TraceState string
 
 const (
@@ -145,6 +145,7 @@ const (
 	StatusCodeError = StatusCode(otlptrace.Status_STATUS_CODE_ERROR)
 )
 
+// String returns the string representation of the StatusCode.
 func (sc StatusCode) String() string { return otlptrace.Status_StatusCode(sc).String() }
 
 // SetCode replaces the code associated with this SpanStatus.

consumer/simple/metrics.go

@@ -352,7 +352,7 @@ func (mb *SafeMetrics) AddHistogramRawDataPoint(name string, hist pdata.IntHisto
 	return mb
 }
 
-// AddDHistogramRawDataPoint wraps AddDHistogramRawDataPoint.
+// AddDHistogramRawDataPoint wraps Metrics.AddDHistogramRawDataPoint.
 func (mb *SafeMetrics) AddDHistogramRawDataPoint(name string, hist pdata.HistogramDataPoint) *SafeMetrics {
 	mb.Lock()
 	mb.Metrics.AddDHistogramRawDataPoint(name, hist)