Restore public API reference documentation

diagnostic.go

@@ -7,14 +7,18 @@ import (
 )
 
 // LoadError reports safe structured diagnostics for a failed configuration load.
+// It intentionally does not expose or unwrap parser and application errors.
 type LoadError struct{ value *engine.LoadError }
 
+// Error implements error without rendering diagnostic messages or input values.
 func (e *LoadError) Error() string {
 	if e == nil || e.value == nil {
 		return "configkit: configuration load failed"
 	}
 	return e.value.Error()
 }
+
+// Diagnostics returns a deep copy of the error's canonical diagnostics.
 func (e *LoadError) Diagnostics() []Diagnostic {
 	if e == nil || e.value == nil {
 		return nil
@@ -29,6 +33,8 @@ func (e *LoadError) Diagnostics() []Diagnostic {
 	}
 	return result
 }
+
+// Sources returns a deep copy of sources discovered before loading failed.
 func (e *LoadError) Sources() []SourceInfo {
 	if e == nil || e.value == nil {
 		return nil
@@ -44,7 +50,8 @@ func (e *LoadError) Sources() []SourceInfo {
 	return result
 }
 
-// WriteDiagnostics writes diagnostics in canonical order.
+// WriteDiagnostics writes diagnostics in canonical order. It escapes terminal
+// control characters and propagates writer errors, including short writes.
 func WriteDiagnostics(output io.Writer, diagnostics []Diagnostic) error {
 	return engine.WriteDiagnostics(output, toEngineDiagnostics(diagnostics))
 }