Reconcile module docs and release materials

flag_values.go

@@ -11,13 +11,17 @@ var ErrFlagInput = errors.New("required flag input is missing")
 // ErrFlagWiring identifies an invalid captured binding or destination.
 var ErrFlagWiring = errors.New("flag wiring is invalid")
 
-// FlagValues stores invocation-local values prepared for captured flags.
+// FlagValues stores invocation-local converted values and presence for captured
+// flags. It does not retain an input instance; values can be applied to
+// independently initialized destinations.
 type FlagValues[I any] struct {
 	values map[*bindingIdentity]preparedValue[I]
 }
 
-// CaptureFlags adapts flags declared for I into flags on Outer. The returned
-// flags preserve the original identities and store prepared values in target.
+// CaptureFlags adapts flags declared for I into flags on Outer. During parsing,
+// each adapted flag stores its prepared value in target, associated with the
+// original inner binding identity. Copies of an original handle remain
+// selectable; an independently constructed lookalike does not.
 func CaptureFlags[Outer, I any](flags []Flag[I], target func(*Outer) *FlagValues[I]) []Flag[Outer] {
 	captured := make([]Flag[Outer], len(flags))
 	for index, original := range flags {
@@ -59,8 +63,10 @@ func CaptureFlags[Outer, I any](flags []Flag[I], target func(*Outer) *FlagValues
 	return captured
 }
 
-// ApplyTo applies selected captured flags to an initialized destination.
-// Repeated core-owned values are copied for each application.
+// ApplyTo applies selected original captured flags to an initialized
+// destination. A missing captured binding or nil destination matches
+// ErrFlagWiring. A required selected value that was not supplied matches
+// ErrFlagInput. Repeated core-owned values are copied for each application.
 func (values FlagValues[I]) ApplyTo(target *I, selected ...Flag[I]) error {
 	if target == nil {
 		return fmt.Errorf("%w: destination is nil", ErrFlagWiring)