[chore] [pdata] update comments to make it clear which functions panic (

#9107)

**Description:** 
This updates comments and adds tests based on
#9070

**Link to tracking Issue:** #9070

**Testing:** This only updates comments, but I have added unit tests to
verify the behaviour described in comments

pdata/pcommon/map.go

@@ -11,6 +11,9 @@ import (
 )
 
 // Map stores a map of string keys to elements of Value type.
+//
+// Must use NewMap function to create new instances.
+// Important: zero-initialized instance is not valid for use.
 type Map internal.Map
 
 // NewMap creates a Map with 0 elements.
@@ -55,8 +58,8 @@ func (m Map) EnsureCapacity(capacity int) {
 // It is allowed to modify the returned value using Value.Set* functions.
 // Such modification will be applied to the value stored in this map.
 //
-// If the key does not exist returns an invalid instance of the KeyValue and false.
-// Calling any functions on the returned invalid instance will cause a panic.
+// If the key does not exist returns a zero-initialized KeyValue and false.
+// Calling any functions on the returned invalid instance may cause a panic.
 func (m Map) Get(key string) (Value, bool) {
 	for i := range *m.getOrig() {
 		akv := &(*m.getOrig())[i]

pdata/pcommon/map_test.go

@@ -519,3 +519,30 @@ func generateTestBytesMap(t *testing.T) Map {
 	assert.NoError(t, m.FromRaw(map[string]any{"k": []byte{1, 2, 3, 4, 5}}))
 	return m
 }
+
+func TestInvalidMap(t *testing.T) {
+	v := Map{}
+
+	testFunc := func(s string, v Value) bool {
+		return true
+	}
+
+	assert.Panics(t, func() { v.Clear() })
+	assert.Panics(t, func() { v.EnsureCapacity(1) })
+	assert.Panics(t, func() { v.Get("foo") })
+	assert.Panics(t, func() { v.Remove("foo") })
+	assert.Panics(t, func() { v.RemoveIf(testFunc) })
+	assert.Panics(t, func() { v.PutEmpty("foo") })
+	assert.Panics(t, func() { v.PutStr("foo", "bar") })
+	assert.Panics(t, func() { v.PutInt("foo", 1) })
+	assert.Panics(t, func() { v.PutDouble("foo", 1.1) })
+	assert.Panics(t, func() { v.PutBool("foo", true) })
+	assert.Panics(t, func() { v.PutEmptyBytes("foo") })
+	assert.Panics(t, func() { v.PutEmptyMap("foo") })
+	assert.Panics(t, func() { v.PutEmptySlice("foo") })
+	assert.Panics(t, func() { v.Len() })
+	assert.Panics(t, func() { v.Range(testFunc) })
+	assert.Panics(t, func() { v.CopyTo(NewMap()) })
+	assert.Panics(t, func() { v.AsRaw() })
+	assert.Panics(t, func() { _ = v.FromRaw(map[string]any{"foo": "bar"}) })
+}

pdata/pcommon/slice_test.go

@@ -136,3 +136,17 @@ func TestSlice_RemoveIf(t *testing.T) {
 	})
 	assert.Equal(t, 5, filtered.Len())
 }
+
+func TestInvalidSlice(t *testing.T) {
+	es := Slice{}
+
+	assert.Panics(t, func() { es.Len() })
+	assert.Panics(t, func() { es.At(0) })
+	assert.Panics(t, func() { es.CopyTo(Slice{}) })
+	assert.Panics(t, func() { es.EnsureCapacity(1) })
+	assert.Panics(t, func() { es.AppendEmpty() })
+	assert.Panics(t, func() { es.MoveAndAppendTo(Slice{}) })
+	assert.Panics(t, func() { es.RemoveIf(func(Value) bool { return false }) })
+	assert.Panics(t, func() { es.AsRaw() })
+	assert.Panics(t, func() { _ = es.FromRaw([]any{3}) })
+}

pdata/pcommon/trace_state.go

@@ -8,6 +8,9 @@ import (
 )
 
 // TraceState represents the trace state from the w3c-trace-context.
+//
+// Must use NewTraceState function to create new instances.
+// Important: zero-initialized instance is not valid for use.
 type TraceState internal.TraceState
 
 func NewTraceState() TraceState {

pdata/pcommon/trace_state_test.go

@@ -35,3 +35,12 @@ func TestTraceState_FromRaw_AsRaw(t *testing.T) {
 	ms.FromRaw("congo=t61rcWkgMzE")
 	assert.Equal(t, "congo=t61rcWkgMzE", ms.AsRaw())
 }
+
+func TestInvalidTraceState(t *testing.T) {
+	v := TraceState{}
+
+	assert.Panics(t, func() { v.AsRaw() })
+	assert.Panics(t, func() { v.FromRaw("") })
+	assert.Panics(t, func() { v.MoveTo(TraceState{}) })
+	assert.Panics(t, func() { v.CopyTo(TraceState{}) })
+}