Restore public API reference documentation

path.go

@@ -5,7 +5,12 @@ import (
 )
 
 // Path identifies a configuration value using YAML field names. Its textual form
-// is a JSON Pointer. Paths are immutable; the zero value is the root path.
+// is a JSON Pointer: the root is empty, ~ escapes as ~0, and / escapes as ~1.
+// Paths are semantic rather than filesystem or URL paths: empty, dot, dot-dot,
+// percent-containing, and numeric keys retain their literal meaning. Parsed
+// numeric tokens are resolved only when traversal knows their containing type.
+//
+// Paths are immutable. The zero value is the root path.
 type Path struct {
 	value engine.Path
 }
@@ -13,7 +18,9 @@ type Path struct {
 // Keys constructs a path of mapping keys. Keys with no arguments returns the root path.
 func Keys(keys ...string) Path { return Path{value: engine.Keys(keys...)} }
 
-// ParsePath parses a JSON Pointer while preserving context-dependent numeric tokens.
+// ParsePath parses a JSON Pointer. Numeric tokens remain unresolved until schema
+// or document traversal determines whether the containing value is a mapping or
+// sequence.
 func ParsePath(pointer string) (Path, error) {
 	value, err := engine.ParsePath(pointer)
 	return Path{value: value}, err
@@ -23,6 +30,7 @@ func ParsePath(pointer string) (Path, error) {
 func (p Path) Key(key string) Path { return Path{value: p.value.Key(key)} }
 
 // Index returns a new path with index appended as a sequence-index segment.
+// A negative index produces an invalid path that configuration operations reject.
 func (p Path) Index(index int) Path { return Path{value: p.value.Index(index)} }
 
 // String returns the path's canonical JSON Pointer spelling.