[configoptional] Make Unmarshal into None[T] match unmarshal into (*T)(nil) (open-telemetry#13168)

<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue.
Ex. Adding a feature - Explain what this achieves.-->
#### Description

Makes it so that unmarshaling into a `None[T]` is equivalent to
unmarshaling into a `(*T)(nil)`.
The goal is to be able to do open-telemetry#13109 without introducing any changes to
the behavior.

Needs open-telemetry#13161.

<!--Describe what testing was performed and which tests were added.-->
#### Testing

Add a unit test to compare the behavior of unmarshaling into `(*T)(nil)`
with that of unmarshaling into `None[T]`

<!--Describe the documentation added.-->
#### Documentation

Amend docstrings

<!--Please delete paragraphs that you did not use before submitting.-->

---------

Co-authored-by: Evan Bradley <[email protected]>

Author: mx-psi

.chloggen/mx-psi_configoptional-to-none-unmarshal.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: configoptional
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Make unmarshaling into `None[T]` work the same as unmarshaling into `(*T)(nil)`."
+
+# One or more tracking issues or pull requests related to the change
+issues: [13168]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [api]

config/configoptional/optional.go

@@ -24,6 +24,10 @@ type Optional[T any] struct {
 
 	// hasValue indicates if the Optional has a value.
 	hasValue bool
+
+	// notNone is used to indicate that the Optional is not None.
+	// This is used to differentiate between None and Default.
+	notNone bool
 }
 
 // deref a reflect.Type to its underlying type.
@@ -82,7 +86,7 @@ func Some[T any](value T) Optional[T] {
 	if err := assertNoEnabledField[T](); err != nil {
 		panic(err)
 	}
-	return Optional[T]{value: value, hasValue: true}
+	return Optional[T]{value: value, hasValue: true, notNone: true}
 }
 
 // Default creates an Optional with a default value for unmarshaling.
@@ -95,13 +99,11 @@ func Default[T any](value T) Optional[T] {
 	if err != nil {
 		panic(err)
 	}
-	return Optional[T]{value: value, hasValue: false}
+	return Optional[T]{value: value, hasValue: false, notNone: true}
 }
 
-// None has no value.
+// None has no value. It has the same behavior as a nil pointer when unmarshaling.
 //
-// For T of struct or pointer to struct kind, this is equivalent to
-// Default(zeroVal) where zeroVal is the zero value of type T.
 // The zero value of Optional[T] is None[T]. Prefer using this constructor
 // for validation.
 //
@@ -131,13 +133,25 @@ var _ confmap.Unmarshaler = (*Optional[any])(nil)
 
 // Unmarshal the configuration into the Optional value.
 //
+// The behavior of this method depends on the state of the Optional:
+//   - None[T]: does nothing if the configuration is nil, otherwise it unmarshals into the zero value of T.
+//   - Some[T](val): equivalent to unmarshaling into a field of type T with value val.
+//   - Default[T](val), equivalent to unmarshaling into a field of type T with base value val,
+//     using val without overrides from the configuration if the configuration is nil.
+//
 // T must be derefenceable to a type with struct kind and not have an 'enabled' field.
 // Scalar values are not supported.
 func (o *Optional[T]) Unmarshal(conf *confmap.Conf) error {
 	if err := assertNoEnabledField[T](); err != nil {
 		return err
 	}
 
+	if !o.hasValue && !o.notNone && conf.ToStringMap() == nil {
+		// If the Optional is None and the configuration is nil, we do nothing.
+		// This replicates the behavior of unmarshaling into a field with a nil pointer.
+		return nil
+	}
+
 	if err := conf.Unmarshal(&o.value); err != nil {
 		return err
 	}

config/configoptional/optional_test.go

@@ -153,21 +153,20 @@ func TestUnmarshalOptional(t *testing.T) {
 				"sub": nil,
 			},
 			defaultCfg: Config[Sub]{
-				Sub1: Default(subDefault),
+				Sub1: None[Sub](),
 			},
-			expectedSub: true,
-			expectedFoo: "foobar", // default applies
+			expectedSub: false,
 		},
 		{
 			name: "none_with_config_no_foo_empty_map",
 			config: map[string]any{
 				"sub": map[string]any{},
 			},
 			defaultCfg: Config[Sub]{
-				Sub1: Default(subDefault),
+				Sub1: None[Sub](),
 			},
 			expectedSub: true,
-			expectedFoo: "foobar", // default applies
+			expectedFoo: "",
 		},
 		{
 			name: "default_no_config",
@@ -200,6 +199,17 @@ func TestUnmarshalOptional(t *testing.T) {
 			expectedSub: true,
 			expectedFoo: "foobar", // default applies
 		},
+		{
+			name: "default_with_config_no_foo_empty_map",
+			config: map[string]any{
+				"sub": map[string]any{},
+			},
+			defaultCfg: Config[Sub]{
+				Sub1: Default(subDefault),
+			},
+			expectedSub: true,
+			expectedFoo: "foobar", // default applies
+		},
 		{
 			name: "some_no_config",
 			defaultCfg: Config[Sub]{
@@ -319,3 +329,39 @@ func TestSquashedOptional(t *testing.T) {
 	assert.True(t, cfg.HasValue())
 	assert.Equal(t, 42, cfg.Get().Val)
 }
+
+func confFromYAML(t *testing.T, yaml string) *confmap.Conf {
+	t.Helper()
+	cm, err := confmap.NewRetrievedFromYAML([]byte(yaml))
+	require.NoError(t, err)
+	conf, err := cm.AsConf()
+	require.NoError(t, err)
+	return conf
+}
+
+func TestComparePointer(t *testing.T) {
+	tests := []struct {
+		yaml string
+	}{
+		{yaml: "sub: "},
+		{yaml: "sub: null"},
+		{yaml: "sub: {}"},
+		{yaml: "sub: {foo: bar}"},
+	}
+	for _, test := range tests {
+		t.Run(test.yaml, func(t *testing.T) {
+			var optCfg Config[Sub]
+			conf := confFromYAML(t, test.yaml)
+			optErr := conf.Unmarshal(&optCfg)
+			require.NoError(t, optErr)
+
+			var ptrCfg struct {
+				Sub1 *Sub `mapstructure:"sub"`
+			}
+			ptrErr := conf.Unmarshal(&ptrCfg)
+			require.NoError(t, ptrErr)
+
+			assert.Equal(t, optCfg.Sub1.Get(), ptrCfg.Sub1)
+		})
+	}
+}