Make consumer documentation easier to follow

inspection.go

@@ -6,15 +6,18 @@ import (
 	"go.maximumdirect.net/configkit/internal/engine"
 )
 
-// ValueSnapshot is a detached, deterministic YAML representation of one value.
-// Present distinguishes absence or deletion from an explicit null value.
+// ValueSnapshot describes a saved value as consistently formatted YAML text.
+// It is a copy; changing it cannot affect later inspection. Present is false for
+// absence or deletion, while explicit null is present. Redacted reports whether
+// the value or a descendant was hidden.
 type ValueSnapshot struct {
 	Present  bool
 	Redacted bool
 	YAML     string
 }
 
-// ValueChange describes one explicit definition or audited domain operation.
+// ValueChange shows values before and after an input contribution or recorded
+// application operation, together with its origin, reasons, and dependencies.
 type ValueChange struct {
 	Before       ValueSnapshot
 	After        ValueSnapshot
@@ -29,7 +32,8 @@ type SecretReferenceInfo struct {
 	Name string
 }
 
-// Explanation is a detached safe account of one effective or historical path.
+// Explanation describes a path's final value and earlier contributions, with
+// sensitive values hidden. It is a copy that cannot alter later inspection.
 type Explanation struct {
 	Path            Path
 	Effective       ValueSnapshot
@@ -38,9 +42,10 @@ type Explanation struct {
 	SecretReference *SecretReferenceInfo
 }
 
-// Explain returns safe effective and chronological values for a known final or
-// historical path. Structural inheritance appears between source applications
-// and typed reconciliation. Unknown and malformed paths return false.
+// Explain returns the saved final value and earlier values for a known current
+// or historical path, hiding sensitive information. History follows processing
+// order: inheritance appears after source combination and before the transition
+// to typed values. Unknown and malformed paths return false.
 func (r *Result[T]) Explain(path Path) (Explanation, bool) {
 	if r == nil {
 		return Explanation{}, false
@@ -49,8 +54,9 @@ func (r *Result[T]) Explain(path Path) (Explanation, bool) {
 	return fromEngineExplanation(value), ok
 }
 
-// WriteEffective writes deterministic redacted YAML from the frozen resolved
-// snapshot. The output is intended for inspection and is not promised reloadable.
+// WriteEffective writes consistently formatted YAML for the saved final
+// configuration, with sensitive values hidden. Later changes to Result.Config
+// do not change the output. It is for inspection and is not promised reloadable.
 // Writer errors, including short writes, are returned and may leave partial output.
 func (r *Result[T]) WriteEffective(output io.Writer) error {
 	if r == nil {
@@ -61,7 +67,7 @@ func (r *Result[T]) WriteEffective(output io.Writer) error {
 }
 
 // WriteExplanation writes a deterministic human-readable rendering of Explain.
-// Unknown paths produce no output. Writer failures may leave partial output.
+// Unknown paths return an error without output. Writer failures may leave partial output.
 func (r *Result[T]) WriteExplanation(output io.Writer, path Path) error {
 	if r == nil {
 		var inspection *engine.Inspection