docs: unify doc comments for functions returning bool (#7064)

Fixes https://github.com/open-telemetry/opentelemetry-go/issues/7063

If also fixes Go Doc comment for `SpanID.IsEmpty`.

The pattern is based on the way the Go standard library documents
functions returning a boolean.

attribute/encoder.go

@@ -128,8 +128,8 @@ func copyAndEscape(buf *bytes.Buffer, val string) {
 	}
 }
 
-// Valid returns true if this encoder ID was allocated by
-// `NewEncoderID`.  Invalid encoder IDs will not be cached.
+// Valid reports whether this encoder ID was allocated by
+// [NewEncoderID]. Invalid encoder IDs will not be cached.
 func (id EncoderID) Valid() bool {
 	return id.value != 0
 }

attribute/iterator.go

@@ -25,8 +25,8 @@ type oneIterator struct {
 	attr KeyValue
 }
 
-// Next moves the iterator to the next position. Returns false if there are no
-// more attributes.
+// Next moves the iterator to the next position.
+// Next reports whether there are more attributes.
 func (i *Iterator) Next() bool {
 	i.idx++
 	return i.idx < i.Len()
@@ -106,7 +106,8 @@ func (oi *oneIterator) advance() {
 	}
 }
 
-// Next returns true if there is another attribute available.
+// Next moves the iterator to the next position.
+// Next reports whether there is another attribute available.
 func (m *MergeIterator) Next() bool {
 	if m.one.done && m.two.done {
 		return false

attribute/key.go

@@ -117,7 +117,7 @@ func (k Key) StringSlice(v []string) KeyValue {
 	}
 }
 
-// Defined returns true for non-empty keys.
+// Defined reports whether the key is not empty.
 func (k Key) Defined() bool {
 	return len(k) != 0
 }

attribute/kv.go

@@ -13,7 +13,7 @@ type KeyValue struct {
 	Value Value
 }
 
-// Valid returns if kv is a valid OpenTelemetry attribute.
+// Valid reports whether kv is a valid OpenTelemetry attribute.
 func (kv KeyValue) Valid() bool {
 	return kv.Key.Defined() && kv.Value.Type() != INVALID
 }

attribute/set.go

@@ -70,7 +70,7 @@ func (d Distinct) reflectValue() reflect.Value {
 	return reflect.ValueOf(d.iface)
 }
 
-// Valid returns true if this value refers to a valid Set.
+// Valid reports whether this value refers to a valid Set.
 func (d Distinct) Valid() bool {
 	return d.iface != nil
 }
@@ -120,7 +120,7 @@ func (l *Set) Value(k Key) (Value, bool) {
 	return Value{}, false
 }
 
-// HasValue tests whether a key is defined in this set.
+// HasValue reports whether a key is defined in this set.
 func (l *Set) HasValue(k Key) bool {
 	if l == nil {
 		return false
@@ -155,7 +155,7 @@ func (l *Set) Equivalent() Distinct {
 	return l.equivalent
 }
 
-// Equals returns true if the argument set is equivalent to this set.
+// Equals reports whether the argument set is equivalent to this set.
 func (l *Set) Equals(o *Set) bool {
 	return l.Equivalent() == o.Equivalent()
 }