[chore] Clarify configopaque expectations (#9295)

Documents `configopaque` expectations.

The intention is that it is clear that we can add interface
implementations after 1.0 if not doing so would leak opaque values.

Fixes #9274

config/configopaque/doc.go

@@ -1,10 +1,21 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
-// Package configopaque implements String type alias to mask sensitive information.
+// Package configopaque implements a String type alias to mask sensitive information.
 // Use configopaque.String on the type of sensitive fields, to mask the
 // opaque string as `[REDACTED]`.
 //
-// This ensures that no sensitive information is leaked when printing the
+// This ensures that no sensitive information is leaked in logs or when printing the
 // full Collector configurations.
+//
+// The only way to view the value stored in a configopaque.String is to first convert
+// it to a string by casting with the builtin `string` function.
+//
+// To achieve this, configopaque.String implements standard library interfaces
+// like fmt.Stringer, encoding.TextMarshaler and others to ensure that the
+// underlying value is masked when printed or serialized.
+//
+// If new interfaces that would leak opaque values are added to the standard library
+// or become widely used in the Go ecosystem, these will eventually be implemented
+// by configopaque.String as well. This is not considered a breaking change.
 package configopaque // import "go.opentelemetry.io/collector/config/configopaque"

config/configopaque/opaque.go

@@ -9,6 +9,7 @@ import (
 )
 
 // String alias that is marshaled and printed in an opaque way.
+// To recover the original value, cast it to a string.
 type String string
 
 const maskedString = "[REDACTED]"