Make consumer documentation easier to follow

lifecycle.go

@@ -6,14 +6,19 @@ import (
 	"go.maximumdirect.net/configkit/internal/engine"
 )
 
-// Definition contains reusable application rules for a configuration type.
-// Sensitive is a pure predicate that can add sensitivity to semantic paths.
-// Definitions should be treated as read-only after being shared.
+// Definition supplies the defaults and application rules used when loading T.
+// Treat a definition as read-only after sharing it. Sensitive is a pure predicate
+// that can mark additional configuration paths for hiding in inspection output.
 type Definition[T any] struct {
-	Defaults  func() T
-	Resolve   func(*T, *Resolution) error
-	Validate  func(*T, *Validation)
-	Version   *VersionRule
+	// Defaults returns starting values for settings omitted from input.
+	Defaults func() T
+	// Resolve derives or normalizes values and records those changes.
+	Resolve func(*T, *Resolution) error
+	// Validate reports application errors and warnings without changing values.
+	Validate func(*T, *Validation)
+	// Version chooses a version path and the application's acceptance rule.
+	Version *VersionRule
+	// Sensitive adds paths to those already hidden by configkit:"secret" tags.
 	Sensitive func(Path) bool
 	// SequenceIdentities declares the scalar fields used to combine records and
 	// resolve record inheritance at selected sequence destinations. Registration
@@ -132,9 +137,10 @@ type Override struct {
 	Flag  string
 }
 
-// Resolution exposes entry-state input provenance, surviving-input presence, and
-// audited application resolution changes. A resolver must not retain or
-// concurrently use the context.
+// Resolution lets a resolver inspect supplied values and record derived defaults
+// or normalization. Its input queries describe the state at callback entry,
+// even after the resolver changes the configuration. Use the context only during
+// the callback; do not retain it or use it concurrently.
 type Resolution struct{ value *engine.Resolution }
 
 // VersionRule declares the input path and application checker for a schema version.
@@ -155,21 +161,27 @@ type Version struct {
 	Text    string
 }
 
-// Validation collects safe application diagnostics during a supported callback.
-// A callback must not retain the context or use it concurrently.
+// Validation lets an application report value-free errors and warnings during
+// a version or validation callback. Use it only during the callback; do not
+// retain the context or use it concurrently.
 type Validation struct{ value *engine.Validation }
 
-// Result is a successful independently owned configuration load.
+// Result contains a successful load's configuration and saved inspection state.
+// The application owns Config and may change it. Inspection continues to describe
+// the completed load; it does not follow later changes to Config. Separate loads
+// return independently owned results.
 type Result[T any] struct {
 	Config T
 
 	inspection *engine.Inspection
 }
 
-// Load parses and strictly decodes zero or one selected source, explicitly enabled
-// imports, and one selected overlay. After source precedence, built-in sibling
-// `extends` relationships resolve before defaults and typed decoding. It accepts
-// at most one Options value and returns no result when any error is reported.
+// Load reads the selected input and returns a configuration of type T with
+// inspection metadata. NoSource deliberately omits the main document. Enabled
+// imports and one selected overlay participate in loading. Sources combine first,
+// then sibling extends relationships resolve before defaults and strict typed
+// decoding. Load accepts at most one Options value and returns a nil result when
+// any error is reported. See docs/config.md for the complete processing order.
 func Load[T any](source Source, supplied ...Options[T]) (*Result[T], error) {
 	options := make([]engine.Options[T], len(supplied))
 	for index := range supplied {
@@ -190,7 +202,8 @@ func fromEngineLoaded[T any](loaded *engine.Loaded[T], err error) (*Result[T], e
 	return &Result[T]{Config: loaded.Config, inspection: loaded.Inspection}, nil
 }
 
-// Metadata returns detached effective presence, origin, and history records.
+// Metadata provides queries for final input presence, value origins, and history.
+// Records returned by its queries are copies that cannot change the saved load.
 func (r *Result[T]) Metadata() Metadata {
 	if r == nil || r.inspection == nil {
 		return Metadata{}
@@ -198,7 +211,8 @@ func (r *Result[T]) Metadata() Metadata {
 	return Metadata{value: r.inspection.Metadata()}
 }
 
-// Sources returns a detached list of sources used by the load.
+// Sources returns a copied list of sources used by the load. Changing the list
+// or its nested records cannot change later queries.
 func (r *Result[T]) Sources() []SourceInfo {
 	if r == nil || r.inspection == nil {
 		return nil