Make consumer documentation easier to follow

records.go

@@ -180,10 +180,10 @@ type Location struct {
 	Column   int
 }
 
-// SourceInfo describes a source discovered during a load. Kind identifies its
-// acquisition, independent of Layer. Path is canonical for a host file and
+// SourceInfo describes one input acquired during loading. Kind says how it was
+// read; Layer says its priority role. Path is canonical for a host file and
 // namespace-relative for a filesystem file; synthetic sources have no Path.
-// Destination is the effective mapping path where this source contributes.
+// Destination says where the source contributes in the assembled configuration.
 // UnderlayIndex is the one-based original underlay position, or zero for other
 // sources. ImportedFrom identifies the declaration that included this source.
 type SourceInfo struct {
@@ -240,12 +240,14 @@ type EmptyImportSelection struct {
 	Selector ImportSelector
 }
 
-// SourceVersionEvidence describes a source-local version declaration observed
-// during an enabled load. A non-nil record with Present false records observed
-// absence, but does not imply that a checker ran or accepted a value. Text is
-// empty when sensitivity classification or conservative callback-time/failed-
-// load redaction withholds it; Present and Null retain their meaning. Copies
-// returned by source queries are detached. See docs/config.md for disclosure
+// SourceVersionEvidence records an observed version declaration in one input
+// document when source-version checks are enabled. A non-nil record with
+// Version.Present false records absence; it does not mean a checker ran or
+// accepted a value. Version.Text is empty when final sensitivity classification
+// or conservative masking during callbacks or failed loads hides it.
+// Version.Present and Version.Null retain their meaning.
+// Source queries return copies you can change without changing stored evidence.
+// See docs/config.md for disclosure
 // and lifecycle details.
 type SourceVersionEvidence struct {
 	Path     Path
@@ -265,9 +267,9 @@ type Diagnostic struct {
 	Related  []Location
 }
 
-// InheritanceStep identifies a concrete payload transfer. From and To name
-// semantic value paths; Reference names the controlling destination `extends`
-// path. Locations belong to that directive, not the transferred value.
+// InheritanceStep identifies values copied from From to To by inheritance.
+// These are configuration paths. Reference names the controlling destination
+// extends path; Locations identify that directive rather than the copied value.
 type InheritanceStep struct {
 	From      Path
 	To        Path
@@ -275,10 +277,10 @@ type InheritanceStep struct {
 	Locations []Location
 }
 
-// Origin describes where an effective definition came from. Multiple locations
-// represent a composite origin; resolution origins are synthetic and identify their
-// operation instead of a file location. Inheritance records the concrete
-// derivation path while Layer and Locations continue to identify value sources.
+// Origin describes where a final value came from. Multiple locations identify
+// contributors to a combined value. Resolution identifies an application operation
+// instead of a file location. Inheritance describes the copying steps, while
+// Layer and Locations still identify the value's sources.
 type Origin struct {
 	Layer       Layer
 	Locations   []Location
@@ -286,7 +288,8 @@ type Origin struct {
 	Inheritance []InheritanceStep
 }
 
-// FieldInfo describes an effective configuration path.
+// FieldInfo describes a final configuration path: whether input supplied it,
+// whether it is null, and where it came from.
 type FieldInfo struct {
 	Explicit bool
 	Null     bool