Update pdata godoc strings (open-telemetry#5226)

- Use copy of the godoc comments from pdata/internal instead of mentioning aliases in pdata/p<signal> public API docs.
- Update godoc strings in both pdata/p<signal> and pdata/internal to keep them consistent.

pdata/internal/cmd/pdatagen/internal/base_slices.go

@@ -111,11 +111,18 @@ func fillTest${structName}(tv ${structName}) {
 	}
 }`
 
-const commonSliceAliasTemplate = `// ${structName} is an alias for ${refPackage}.${structName} struct.
-${extraStructComment}type ${structName} = ${refPackage}.${structName}
+const commonSliceAliasTemplate = `// ${structName} logically represents a slice of ${elementName}.
+//
+// This is a reference type. If passed by value and callee modifies it, the
+// caller will see the modification.
+//
+// Must use New${structName} function to create new instances.
+// Important: zero-initialized instance is not valid for use.
+type ${structName} = internal.${structName}
 
-// New${structName} is an alias for a function to create ${structName}.
-${extraNewComment}var New${structName} = ${refPackage}.New${structName}`
+// New${structName} creates a ${structName} with 0 elements.
+// Can use "EnsureCapacity" to initialize with a given capacity.
+var New${structName} = internal.New${structName}`
 
 const slicePtrTemplate = `// ${structName} logically represents a slice of ${elementName}.
 //
@@ -477,26 +484,13 @@ func (ss *sliceOfPtrs) templateFields() func(name string) string {
 	}
 }
 
-func (ss *sliceOfPtrs) generateAlias(sb *strings.Builder, deprecatedInFavor string) {
+func (ss *sliceOfPtrs) generateAlias(sb *strings.Builder) {
 	sb.WriteString(os.Expand(commonSliceAliasTemplate, func(name string) string {
 		switch name {
 		case "structName":
 			return ss.structName
-		case "refPackage":
-			if deprecatedInFavor == "" {
-				return "internal"
-			}
-			return deprecatedInFavor
-		case "extraStructComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ss.structName + " instead.\n"
-			}
-			return ""
-		case "extraNewComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ss.structName + " instead.\n"
-			}
-			return ""
+		case "elementName":
+			return ss.element.structName
 		default:
 			panic(name)
 		}
@@ -545,26 +539,13 @@ func (ss *sliceOfValues) templateFields() func(name string) string {
 	}
 }
 
-func (ss *sliceOfValues) generateAlias(sb *strings.Builder, deprecatedInFavor string) {
+func (ss *sliceOfValues) generateAlias(sb *strings.Builder) {
 	sb.WriteString(os.Expand(commonSliceAliasTemplate, func(name string) string {
 		switch name {
 		case "structName":
 			return ss.structName
-		case "refPackage":
-			if deprecatedInFavor == "" {
-				return "internal"
-			}
-			return deprecatedInFavor
-		case "extraStructComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ss.structName + " instead.\n"
-			}
-			return ""
-		case "extraNewComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ss.structName + " instead.\n"
-			}
-			return ""
+		case "elementName":
+			return ss.element.structName
 		default:
 			panic(name)
 		}

pdata/internal/cmd/pdatagen/internal/base_structs.go

@@ -78,11 +78,17 @@ const messageValueGenerateTestTemplate = `func generateTest${structName}() ${str
 const messageValueFillTestHeaderTemplate = `func fillTest${structName}(tv ${structName}) {`
 const messageValueFillTestFooterTemplate = `}`
 
-const messageValueAliasTemplate = `// ${structName} is an alias for ${refPackage}.${structName} struct.
-${extraStructComment}type ${structName} = ${refPackage}.${structName} 
+const messageValueAliasTemplate = `${description}
+//
+// This is a reference type, if passed by value and callee modifies it the
+// caller will see the modification.
+//
+// Must use New${structName} function to create new instances.
+// Important: zero-initialized instance is not valid for use.
+type ${structName} = internal.${structName} 
 
 // New${structName} is an alias for a function to create a new empty ${structName}.
-${extraStructComment}var New${structName} = ${refPackage}.New${structName}`
+var New${structName} = internal.New${structName}`
 
 const newLine = "\n"
 
@@ -97,7 +103,7 @@ type baseStruct interface {
 }
 
 type aliasGenerator interface {
-	generateAlias(sb *strings.Builder, deprecatedInFavor string)
+	generateAlias(sb *strings.Builder)
 }
 
 type messageValueStruct struct {
@@ -196,26 +202,13 @@ func (ms *messageValueStruct) generateTestValueHelpers(sb *strings.Builder) {
 	}))
 }
 
-func (ms *messageValueStruct) generateAlias(sb *strings.Builder, deprecatedInFavor string) {
+func (ms *messageValueStruct) generateAlias(sb *strings.Builder) {
 	sb.WriteString(os.Expand(messageValueAliasTemplate, func(name string) string {
 		switch name {
 		case "structName":
 			return ms.structName
-		case "refPackage":
-			if deprecatedInFavor == "" {
-				return "internal"
-			}
-			return deprecatedInFavor
-		case "extraStructComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + "." + ms.structName + " instead.\n"
-			}
-			return ""
-		case "extraNewComment":
-			if deprecatedInFavor != "" {
-				return "// Deprecated: [v0.49.0] Use " + deprecatedInFavor + ".New" + ms.structName + " instead.\n"
-			}
-			return ""
+		case "description":
+			return ms.description
 		default:
 			panic(name)
 		}

pdata/internal/cmd/pdatagen/main.go

@@ -39,20 +39,15 @@ func main() {
 		_, err = f.WriteString(fp.GenerateTestFile())
 		check(err)
 		check(f.Close())
-		f, err = os.Create("./model/pdata/generated_" + fp.Name + "_alias.go")
-		check(err)
 		fileName := "generated_alias.go"
 		packageName := fp.Name
 		if fp.IsCommon() {
 			fileName = "generated_" + fp.Name + "_alias.go"
 			packageName = "pcommon"
 		}
-		_, err = f.WriteString(fp.GenerateAliasFile("pdata", packageName))
-		check(err)
-		check(f.Close())
 		f, err = os.Create(filepath.Clean("./pdata/" + packageName + "/" + fileName))
 		check(err)
-		_, err = f.WriteString(fp.GenerateAliasFile(packageName, ""))
+		_, err = f.WriteString(fp.GenerateAliasFile(packageName))
 		check(err)
 		check(f.Close())
 	}

pdata/internal/common.go

@@ -66,7 +66,7 @@ func (avt ValueType) String() string {
 	return ""
 }
 
-// Value is a mutable cell containing the value of an attribute. Typically used in Map.
+// Value is a mutable cell containing any value. Typically used as an element of Map or Slice.
 // Must use one of NewValue+ functions below to create new instances.
 //
 // Intended to be passed by value since internally it is just a pointer to actual
@@ -547,7 +547,7 @@ func newAttributeKeyValueBytes(k string, v []byte) otlpcommon.KeyValue {
 	return orig
 }
 
-// Map stores a map of attribute keys to values.
+// Map stores a map of string keys to elements of Value type.
 type Map struct {
 	orig *[]otlpcommon.KeyValue
 }

pdata/internal/logs.go

@@ -49,7 +49,7 @@ type Logs struct {
 	orig *otlpcollectorlog.ExportLogsServiceRequest
 }
 
-// NewLogs creates a new Logs.
+// NewLogs creates a new Logs struct.
 func NewLogs() Logs {
 	return Logs{orig: &otlpcollectorlog.ExportLogsServiceRequest{}}
 }
@@ -88,7 +88,7 @@ func (ld Logs) ResourceLogs() ResourceLogsSlice {
 	return newResourceLogsSlice(&ld.orig.ResourceLogs)
 }
 
-// SeverityNumber is the public alias of otlplogs.SeverityNumber from internal package.
+// SeverityNumber represents severity number of a log record.
 type SeverityNumber int32
 
 const (

pdata/internal/metrics.go

@@ -49,7 +49,7 @@ type Metrics struct {
 	orig *otlpcollectormetrics.ExportMetricsServiceRequest
 }
 
-// NewMetrics creates a new Metrics.
+// NewMetrics creates a new Metrics struct.
 func NewMetrics() Metrics {
 	return Metrics{orig: &otlpcollectormetrics.ExportMetricsServiceRequest{}}
 }

pdata/internal/spanid.go

@@ -18,7 +18,7 @@ import (
 	"go.opentelemetry.io/collector/pdata/internal/data"
 )
 
-// SpanID is an alias of OTLP SpanID data type.
+// SpanID is span identifier.
 type SpanID struct {
 	orig data.SpanID
 }

pdata/internal/traceid.go

@@ -18,7 +18,7 @@ import (
 	"go.opentelemetry.io/collector/pdata/internal/data"
 )
 
-// TraceID is an alias of OTLP TraceID data type.
+// TraceID is a trace identifier.
 type TraceID struct {
 	orig data.TraceID
 }

pdata/internal/traces.go

@@ -50,7 +50,7 @@ type Traces struct {
 	orig *otlpcollectortrace.ExportTraceServiceRequest
 }
 
-// NewTraces creates a new Traces.
+// NewTraces creates a new Traces struct.
 func NewTraces() Traces {
 	return Traces{orig: &otlpcollectortrace.ExportTraceServiceRequest{}}
 }

pdata/pcommon/alias.go

@@ -19,7 +19,7 @@ package pcommon // import "go.opentelemetry.io/collector/pdata/pcommon"
 
 import "go.opentelemetry.io/collector/pdata/internal"
 
-// ValueType is an alias for internal.ValueType type.
+// ValueType specifies the type of Value.
 type ValueType = internal.ValueType
 
 const (
@@ -33,26 +33,59 @@ const (
 	ValueTypeBytes  = internal.ValueTypeBytes
 )
 
-// Value is an alias for internal.Value struct.
+// Value is a mutable cell containing any value. Typically used as an element of Map or Slice.
+// Must use one of NewValue+ functions below to create new instances.
+//
+// Intended to be passed by value since internally it is just a pointer to actual
+// value representation. For the same reason passing by value and calling setters
+// will modify the original, e.g.:
+//
+//   func f1(val Value) { val.SetIntVal(234) }
+//   func f2() {
+//       v := NewValueString("a string")
+//       f1(v)
+//       _ := v.Type() // this will return ValueTypeInt
+//   }
+//
+// Important: zero-initialized instance is not valid for use. All Value functions below must
+// be called only on instances that are created via NewValue+ functions.
 type Value = internal.Value
 
-// Aliases for functions to create internal.Value.
 var (
-	NewValueEmpty  = internal.NewValueEmpty
+	// NewValueEmpty creates a new Value with an empty value.
+	NewValueEmpty = internal.NewValueEmpty
+
+	// NewValueString creates a new Value with the given string value.
 	NewValueString = internal.NewValueString
-	NewValueInt    = internal.NewValueInt
+
+	// NewValueInt creates a new Value with the given int64 value.
+	NewValueInt = internal.NewValueInt
+
+	// NewValueDouble creates a new Value with the given float64 value.
 	NewValueDouble = internal.NewValueDouble
-	NewValueBool   = internal.NewValueBool
-	NewValueMap    = internal.NewValueMap
-	NewValueSlice  = internal.NewValueSlice
-	NewValueBytes  = internal.NewValueBytes
+
+	// NewValueBool creates a new Value with the given bool value.
+	NewValueBool = internal.NewValueBool
+
+	// NewValueMap creates a new Value of map type.
+	NewValueMap = internal.NewValueMap
+
+	// NewValueSlice creates a new Value of array type.
+	NewValueSlice = internal.NewValueSlice
+
+	// NewValueBytes creates a new Value with the given []byte value.
+	// The caller must ensure the []byte passed in is not modified after the call is made, sharing the data
+	// across multiple attributes is forbidden.
+	NewValueBytes = internal.NewValueBytes
 )
 
-// Map is an alias for internal.Map struct.
+// Map stores a map of string keys to elements of Value type.
 type Map = internal.Map
 
-// Aliases for functions to create internal.Map.
 var (
-	NewMap        = internal.NewMap
+	// NewMap creates a Map with 0 elements.
+	NewMap = internal.NewMap
+
+	// NewMapFromRaw creates a Map with values from the given map[string]interface{}.
 	NewMapFromRaw = internal.NewMapFromRaw
 )