v0.36.0 doc sweep update

internal/config/config.go

@@ -1,3 +1,8 @@
+// Package config is lw's configuration: the settings and pipeline tables, the
+// plugin catalogue whose option structs' tags are the schema, the pipeline
+// flags, LOGWISP_ variables and presets that build pipelines, and the rules
+// Decode and ValidateConfig apply. Load's Manager merges the file, environment
+// and command line, and rereads the file on reload.
 package config
 
 // --- LogWisp Configuration Options ---
@@ -31,7 +36,7 @@ type LogConfig struct {
 	// File output settings (when Output includes "file" or "all")
 	File *LogFileConfig `toml:"file"`
 
-	// Console output settings
+	// Accepted for older files: logging.output chooses the console
 	Console *LogConsoleConfig `toml:"console"`
 }
 
@@ -44,7 +49,8 @@ type LogFileConfig struct {
 	RetentionHours float64 `toml:"retention_hours" help:"hours a .log file is kept; 0 keeps them"`
 }
 
-// LogConsoleConfig defines settings for console-based application logging
+// LogConsoleConfig is logging.console, whose target has no effect:
+// logging.output chooses the console stream
 type LogConsoleConfig struct {
 	Target string `toml:"target" lw:"enum=stdout|stderr|split" help:"accepted without effect: logging.output chooses the console"`
 }

internal/config/schema.go

@@ -231,9 +231,9 @@ func settingKeys(v reflect.Value, prefix string) []Key {
 }
 
 // Decode reads a plugin's config map into its options: unknown keys, kinds,
-// the defaults, the tag rules, the tls, auth and acl rules of its side, then the
-// options' own Check; a leading ~ in a path is the home directory. It reads no
-// file.
+// the defaults, the tag rules and the options' own Check, then the host, tls,
+// acl and auth rules of its side; a leading ~ in a path is the home directory.
+// It reads no file.
 func Decode[T any](role, typ string, m map[string]any) (*T, error) {
 	v, err := decode(role, typ, m)
 	if err != nil {
@@ -272,7 +272,8 @@ func decode(role, typ string, m map[string]any) (any, error) {
 }
 
 // Settle gives a decoded table its defaults, applies the tag rules, then its
-// own Check: Decode's last steps, for the flow stages a file decodes typed
+// own Check, as Decode does before its side's rules, for the flow stages a
+// file decodes typed
 func Settle(v any) error {
 	Fill(v)
 	if err := checkTags(reflect.ValueOf(v).Elem(), ""); err != nil {

internal/config/spec.go

@@ -238,7 +238,8 @@ func SpecPipelines(specs []Spec, isDir IsDir) ([]PipelineConfig, error) {
 }
 
 // buildPipelines turns specs, in order, into pipelines; specs before the first
-// --pipeline go to one named "cli". Every call returns fresh maps.
+// --pipeline go to one named after the preset that starts it, or else "cli".
+// Every call returns fresh maps.
 func buildPipelines(specs []pipelineSpec, isDir IsDir) ([]PipelineConfig, error) {
 	var pipelines []PipelineConfig
 	var seen map[*specKind]bool

internal/config/validate.go

@@ -25,7 +25,8 @@ import (
 // ValidateConfig checks a configuration without reading a file it names:
 // the settings, then each pipeline's flow stages, and its sources and sinks
 // decoded in full. Its error joins every problem, one a part, each a
-// *KeyError naming the path of the refused key. lw --check opens the files.
+// *KeyError naming the refused key's path, save "no pipelines configured".
+// lw --check opens the files.
 func ValidateConfig(cfg *Config) error {
 	if cfg == nil {
 		return fmt.Errorf("config is nil")
@@ -521,9 +522,11 @@ func (c *FilterConfig) Check() error {
 	return nil
 }
 
-// Scan decodes a flow stage's command-line map into target, rejecting keys
-// target does not declare: a misspelled key must fail, not be dropped. Its
-// values take their kinds as a plugin's do, a wrong one refused at its key.
+// Scan decodes a table into target: a flow stage from a spec or an edit, a
+// file's root or the website's pipelines. It refuses a key target does not
+// declare, nested tables' too: a misspelled key must fail, not be dropped.
+// Values outside a list of tables take their kinds as a plugin's do, a wrong
+// one refused at its key.
 func Scan(configMap map[string]any, target any) error {
 	if err := checkKeys(configMap, reflect.TypeOf(target), ""); err != nil {
 		return err
@@ -580,7 +583,7 @@ func checkKeys(m map[string]any, t reflect.Type, prefix string) error {
 
 // checkFileKeys rejects keys the configuration file declares that Config does
 // not: a misspelled table path such as plugin_sinks.confg.tls would otherwise
-// drop the whole table. Plugin config maps are checked by Scan instead.
+// drop the whole table. Plugin config maps are checked by Decode instead.
 func checkFileKeys(path string) error {
 	data, err := os.ReadFile(path)
 	if errors.Is(err, fs.ErrNotExist) {