Add example functions to demonstrate package usage

[sgaunet]

Problem

Public API functions lack Go example functions demonstrating typical usage patterns.

Missing Examples

No Example*() functions in any package:

• pkg/config - No examples of loading/validating config
• pkg/formatter - No examples of creating/using formatter
• pkg/processor - No examples of processing streams
• pkg/executor - No examples of executing commands

Proposed Examples

Example 1: config package

// pkg/config/example_test.go

func ExampleLoad() {
    // Load config from file
    cfg, err := Load("testdata/example.yaml")
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Format: %s\n", cfg.Output.Format)
    fmt.Printf("Default level: %s\n", cfg.LogLevel.Default)
    // Output:
    // Format: text
    // Default level: INFO
}

func ExampleConfig_Validate() {
    cfg := &Config{
        Output: OutputConfig{
            Format: "json",
        },
        LogLevel: LogLevelConfig{
            Default: "INFO",
        },
    }
    
    if err := cfg.Validate(); err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Config is valid")
    // Output: Config is valid
}

Example 2: formatter package

// pkg/formatter/example_test.go

func ExampleNew() {
    cfg := &config.Config{
        Prefix: config.PrefixConfig{
            Template: "[{{.Level}}] ",
        },
        LogLevel: config.LogLevelConfig{
            Default: "INFO",
        },
    }
    
    f, err := New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    
    output := f.Format("ERROR: something went wrong", "stderr")
    fmt.Println(output)
    // Output: [ERROR] ERROR: something went wrong
}

func ExampleFormatter_Format() {
    cfg := &config.Config{
        Prefix: config.PrefixConfig{
            Template: "{{.Stream}}: ",
        },
    }
    
    f, _ := New(cfg)
    
    stdout := f.Format("normal output", "stdout")
    stderr := f.Format("error output", "stderr")
    
    fmt.Println(stdout)
    fmt.Println(stderr)
    // Output:
    // stdout: normal output
    // stderr: error output
}

Example 3: executor package

// pkg/executor/example_test.go

func ExampleExecutor_Execute() {
    exec := New()
    
    exitCode, err := exec.Execute("echo", []string{"hello", "world"})
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Exit code: %d\n", exitCode)
    // Output: Exit code: 0
}

func ExampleExecutor_Execute_failure() {
    exec := New()
    
    _, err := exec.Execute("nonexistent", []string{})
    if err != nil {
        fmt.Println("Command failed")
    }
    // Output: Command failed
}

Example 4: processor package

// pkg/processor/example_test.go

func ExampleProcessor_ProcessStreams() {
    cfg := &config.Config{/* ... */}
    formatter, _ := formatter.New(cfg)
    proc := New(cfg, formatter)
    
    // Create fake streams
    stdout := strings.NewReader("line 1\nline 2\n")
    stderr := strings.NewReader("error 1\n")
    
    err := proc.ProcessStreams(stdout, stderr, "stdout", "stderr")
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Processing complete")
    // Output: Processing complete
}

Benefits

Documentation:

• Executable examples appear in godoc
• Examples tested automatically (go test)
• Show real-world usage patterns

User Experience:

• Quick start guide via examples
• Copy-paste ready code snippets
• Demonstrates best practices

Quality Assurance:

• Examples must compile
• Output verified via // Output: comments
• Breaking changes caught by failing examples

Implementation Checklist

High Priority:

• Add examples to pkg/config
• Add examples to pkg/formatter
• Add examples to pkg/executor

Medium Priority:

• Add examples to pkg/processor
• Add examples to cmd/logwrap (main usage)
• Create testdata/ files for examples

Nice to Have:

• Add examples for error cases
• Add examples for advanced usage
• Add examples to README

Example Test File Structure

pkg/
├── config/
│   ├── config.go
│   ├── config_test.go
│   └── example_test.go        # New file
├── formatter/
│   ├── formatter.go
│   ├── formatter_test.go
│   └── example_test.go        # New file
└── executor/
    ├── executor.go
    ├── executor_test.go
    └── example_test.go        # New file

Running Examples

# Run example tests
go test -run Example ./pkg/...

# View examples in godoc
go doc -all github.com/sgaunet/logwrap/pkg/formatter

# Generate godoc HTML
godoc -http=:6060
# Visit http://localhost:6060/pkg/github.com/sgaunet/logwrap/

Example Guidelines

1. Keep it simple:

// Good - simple and focused
func ExampleNew() {
    cfg := &Config{Format: "json"}
    f := New(cfg)
    fmt.Println(f.Format("test", "stdout"))
}

// Bad - too complex for an example
func ExampleNew() {
    cfg, err := LoadConfig()
    if err != nil { /* complex error handling */ }
    f, err := New(cfg)
    // 20 more lines...
}

2. Use Output comments:

func ExampleFormat() {
    fmt.Println("result")
    // Output: result
}

3. Test automatically:

$ go test -run ExampleFormat
PASS

Related Issues

• Add comprehensive package-level documentation #14 - Package documentation (examples complement godoc)
• Add end-to-end integration tests for complete pipeline #9 - Integration tests (examples can serve as integration tests)

References

• Go by Example: https://gobyexample.com/
• Effective Go: Examples
• Testing package: https://pkg.go.dev/testing#hdr-Examples