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()
 }

bridge/opencensus/internal/span.go

@@ -39,7 +39,7 @@ func NewSpan(s trace.Span) *octrace.Span {
 	return octrace.NewSpan(&Span{otelSpan: s})
 }
 
-// IsRecordingEvents returns true if events are being recorded for this span.
+// IsRecordingEvents reports whether events are being recorded for this span.
 func (s *Span) IsRecordingEvents() bool {
 	return s.otelSpan.IsRecording()
 }

log/keyvalue.go

@@ -242,10 +242,10 @@ func (v Value) Kind() Kind {
 	}
 }
 
-// Empty returns if v does not hold any value.
+// Empty reports whether v does not hold any value.
 func (v Value) Empty() bool { return v.Kind() == KindEmpty }
 
-// Equal returns if v is equal to w.
+// Equal reports whether v is equal to w.
 func (v Value) Equal(w Value) bool {
 	k1 := v.Kind()
 	k2 := w.Kind()
@@ -326,7 +326,7 @@ type KeyValue struct {
 	Value Value
 }
 
-// Equal returns if a is equal to b.
+// Equal reports whether a is equal to b.
 func (a KeyValue) Equal(b KeyValue) bool {
 	return a.Key == b.Key && a.Value.Equal(b.Value)
 }

log/logger.go

@@ -30,7 +30,7 @@ type Logger interface {
 	// concurrently.
 	Emit(ctx context.Context, record Record)
 
-	// Enabled returns whether the Logger emits for the given context and
+	// Enabled reports whether the Logger emits for the given context and
 	// param.
 	//
 	// This is useful for users that want to know if a [Record]

sdk/internal/x/x.go

@@ -59,7 +59,7 @@ func (f Feature[T]) Lookup() (v T, ok bool) {
 	return f.parse(vRaw)
 }
 
-// Enabled returns if the feature is enabled.
+// Enabled reports whether the feature is enabled.
 func (f Feature[T]) Enabled() bool {
 	_, ok := f.Lookup()
 	return ok

sdk/log/filter_processor.go

@@ -30,7 +30,7 @@ import (
 // It provides a Processor used to filter out [Record]
 // that has a [log.Severity] below a threshold.
 type FilterProcessor interface {
-	// Enabled returns whether the Processor will process for the given context
+	// Enabled reports whether the Processor will process for the given context
 	// and param.
 	//
 	// The passed param is likely to be a partial record information being

sdk/metric/instrument.go

@@ -75,7 +75,7 @@ type Instrument struct {
 	nonComparable // nolint: unused
 }
 
-// IsEmpty returns if all Instrument fields are their zero-value.
+// IsEmpty reports whether all Instrument fields are their zero-value.
 func (i Instrument) IsEmpty() bool {
 	return i.Name == "" &&
 		i.Description == "" &&

sdk/metric/internal/x/x.go

@@ -63,7 +63,7 @@ func (f Feature[T]) Lookup() (v T, ok bool) {
 	return f.parse(vRaw)
 }
 
-// Enabled returns if the feature is enabled.
+// Enabled reports whether the feature is enabled.
 func (f Feature[T]) Enabled() bool {
 	_, ok := f.Lookup()
 	return ok
@@ -73,7 +73,7 @@ func (f Feature[T]) Enabled() bool {
 //
 // EnabledInstrument interface is implemented by synchronous instruments.
 type EnabledInstrument interface {
-	// Enabled returns whether the instrument will process measurements for the given context.
+	// Enabled reports whether the instrument will process measurements for the given context.
 	//
 	// This function can be used in places where measuring an instrument
 	// would result in computationally expensive operations.

sdk/resource/os_release_unix.go

@@ -63,7 +63,7 @@ func parseOSReleaseFile(file io.Reader) map[string]string {
 	return values
 }
 
-// skip returns true if the line is blank or starts with a '#' character, and
+// skip reports whether the line is blank or starts with a '#' character, and
 // therefore should be skipped from processing.
 func skip(line string) bool {
 	line = strings.TrimSpace(line)

sdk/resource/resource.go

@@ -148,7 +148,7 @@ func (r *Resource) Iter() attribute.Iterator {
 	return r.attrs.Iter()
 }
 
-// Equal returns whether r and o represent the same resource. Two resources can
+// Equal reports whether r and o represent the same resource. Two resources can
 // be equal even if they have different schema URLs.
 //
 // See the documentation on the [Resource] type for the pitfalls of using ==

sdk/trace/internal/x/x.go

@@ -56,7 +56,7 @@ func (f Feature[T]) Lookup() (v T, ok bool) {
 	return f.parse(vRaw)
 }
 
-// Enabled returns if the feature is enabled.
+// Enabled reports whether the feature is enabled.
 func (f Feature[T]) Enabled() bool {
 	_, ok := f.Lookup()
 	return ok

sdk/trace/span.go

@@ -167,7 +167,7 @@ func (s *recordingSpan) SpanContext() trace.SpanContext {
 	return s.spanContext
 }
 
-// IsRecording returns if this span is being recorded. If this span has ended
+// IsRecording reports whether this span is being recorded. If this span has ended
 // this will return false.
 func (s *recordingSpan) IsRecording() bool {
 	if s == nil {
@@ -179,7 +179,7 @@ func (s *recordingSpan) IsRecording() bool {
 	return s.isRecording()
 }
 
-// isRecording returns if this span is being recorded. If this span has ended
+// isRecording reports whether this span is being recorded. If this span has ended
 // this will return false.
 //
 // This method assumes s.mu.Lock is held by the caller.

trace/config.go

@@ -73,7 +73,7 @@ func (cfg *SpanConfig) Timestamp() time.Time {
 	return cfg.timestamp
 }
 
-// StackTrace checks whether stack trace capturing is enabled.
+// StackTrace reports whether stack trace capturing is enabled.
 func (cfg *SpanConfig) StackTrace() bool {
 	return cfg.stackTrace
 }
@@ -154,7 +154,7 @@ func (cfg *EventConfig) Timestamp() time.Time {
 	return cfg.timestamp
 }
 
-// StackTrace checks whether stack trace capturing is enabled.
+// StackTrace reports whether stack trace capturing is enabled.
 func (cfg *EventConfig) StackTrace() bool {
 	return cfg.stackTrace
 }

trace/internal/telemetry/attr.go

@@ -52,7 +52,7 @@ func Map(key string, value ...Attr) Attr {
 	return Attr{key, MapValue(value...)}
 }
 
-// Equal returns if a is equal to b.
+// Equal reports whether a is equal to b.
 func (a Attr) Equal(b Attr) bool {
 	return a.Key == b.Key && a.Value.Equal(b.Value)
 }

trace/internal/telemetry/id.go

@@ -22,7 +22,7 @@ func (tid TraceID) String() string {
 	return hex.EncodeToString(tid[:])
 }
 
-// IsEmpty returns false if id contains at least one non-zero byte.
+// IsEmpty reports whether the TraceID contains only zero bytes.
 func (tid TraceID) IsEmpty() bool {
 	return tid == [traceIDSize]byte{}
 }
@@ -50,7 +50,7 @@ func (sid SpanID) String() string {
 	return hex.EncodeToString(sid[:])
 }
 
-// IsEmpty returns true if the span ID contains at least one non-zero byte.
+// IsEmpty reports whether the SpanID contains only zero bytes.
 func (sid SpanID) IsEmpty() bool {
 	return sid == [spanIDSize]byte{}
 }

trace/internal/telemetry/value.go

@@ -257,10 +257,10 @@ func (v Value) Kind() ValueKind {
 	}
 }
 
-// Empty returns if v does not hold any value.
+// Empty reports whether v does not hold any value.
 func (v Value) Empty() bool { return v.Kind() == ValueKindEmpty }
 
-// Equal returns if v is equal to w.
+// Equal reports whether v is equal to w.
 func (v Value) Equal(w Value) bool {
 	k1 := v.Kind()
 	k2 := w.Kind()

trace/trace.go

@@ -38,7 +38,7 @@ var (
 	_          json.Marshaler = nilTraceID
 )
 
-// IsValid checks whether the trace TraceID is valid. A valid trace ID does
+// IsValid reports whether the trace TraceID is valid. A valid trace ID does
 // not consist of zeros only.
 func (t TraceID) IsValid() bool {
 	return !bytes.Equal(t[:], nilTraceID[:])
@@ -63,7 +63,7 @@ var (
 	_         json.Marshaler = nilSpanID
 )
 
-// IsValid checks whether the SpanID is valid. A valid SpanID does not consist
+// IsValid reports whether the SpanID is valid. A valid SpanID does not consist
 // of zeros only.
 func (s SpanID) IsValid() bool {
 	return !bytes.Equal(s[:], nilSpanID[:])
@@ -143,7 +143,7 @@ func decodeHex(h string, b []byte) error {
 // TraceFlags contains flags that can be set on a SpanContext.
 type TraceFlags byte //nolint:revive // revive complains about stutter of `trace.TraceFlags`.
 
-// IsSampled returns if the sampling bit is set in the TraceFlags.
+// IsSampled reports whether the sampling bit is set in the TraceFlags.
 func (tf TraceFlags) IsSampled() bool {
 	return tf&FlagsSampled == FlagsSampled
 }
@@ -201,13 +201,13 @@ type SpanContext struct {
 
 var _ json.Marshaler = SpanContext{}
 
-// IsValid returns if the SpanContext is valid. A valid span context has a
+// IsValid reports whether the SpanContext is valid. A valid span context has a
 // valid TraceID and SpanID.
 func (sc SpanContext) IsValid() bool {
 	return sc.HasTraceID() && sc.HasSpanID()
 }
 
-// IsRemote indicates whether the SpanContext represents a remotely-created Span.
+// IsRemote reports whether the SpanContext represents a remotely-created Span.
 func (sc SpanContext) IsRemote() bool {
 	return sc.remote
 }
@@ -228,7 +228,7 @@ func (sc SpanContext) TraceID() TraceID {
 	return sc.traceID
 }
 
-// HasTraceID checks if the SpanContext has a valid TraceID.
+// HasTraceID reports whether the SpanContext has a valid TraceID.
 func (sc SpanContext) HasTraceID() bool {
 	return sc.traceID.IsValid()
 }
@@ -249,7 +249,7 @@ func (sc SpanContext) SpanID() SpanID {
 	return sc.spanID
 }
 
-// HasSpanID checks if the SpanContext has a valid SpanID.
+// HasSpanID reports whether the SpanContext has a valid SpanID.
 func (sc SpanContext) HasSpanID() bool {
 	return sc.spanID.IsValid()
 }
@@ -270,7 +270,7 @@ func (sc SpanContext) TraceFlags() TraceFlags {
 	return sc.traceFlags
 }
 
-// IsSampled returns if the sampling bit is set in the SpanContext's TraceFlags.
+// IsSampled reports whether the sampling bit is set in the SpanContext's TraceFlags.
 func (sc SpanContext) IsSampled() bool {
 	return sc.traceFlags.IsSampled()
 }
@@ -302,7 +302,7 @@ func (sc SpanContext) WithTraceState(state TraceState) SpanContext {
 	}
 }
 
-// Equal is a predicate that determines whether two SpanContext values are equal.
+// Equal reports whether two SpanContext values are equal.
 func (sc SpanContext) Equal(other SpanContext) bool {
 	return sc.traceID == other.traceID &&
 		sc.spanID == other.spanID &&