Skip to content

docs(config): document configuration subsystem#344

Merged
kcenon merged 1 commit into
mainfrom
docs/issue-326-document-configuration-subsystem
Feb 8, 2026
Merged

docs(config): document configuration subsystem#344
kcenon merged 1 commit into
mainfrom
docs/issue-326-document-configuration-subsystem

Conversation

@kcenon

@kcenon kcenon commented Feb 8, 2026

Copy link
Copy Markdown
Owner

Closes #326

Summary

Add comprehensive documentation for the configuration subsystem (docs/CONFIG_GUIDE.md) covering all 4 header files:

  • config_watcher.h — Hot-reload file watching with platform-native APIs (inotify/kqueue/ReadDirectoryChangesW)
  • unified_config.h — Type-safe configuration schema with 7 sub-structs
  • cli_config_parser.h — Command-line argument parsing and configuration overrides
  • config_loader.h — YAML file loading, environment variable substitution, and validation

Documentation Contents

1. Configuration Architecture

  • Configuration source priority (CLI > Env > YAML > Defaults)
  • Hot-reload mechanism with debouncing
  • Architecture diagram

2. Unified Config

  • All 7 sub-structs documented: thread, logger, monitoring, database, network
  • Default values for each field
  • Hot-reloadable field identification

3. Config Watcher

  • Cross-platform file system monitoring
  • Callback registration patterns
  • Version tracking and rollback support
  • Thread safety guarantees

4. CLI Config Parser

  • Argument format (--config, --set, --help, --version)
  • Boolean flag parsing
  • Help text generation

5. Config Loader

  • YAML file format support
  • Error handling and validation
  • Environment variable substitution (${VAR_NAME})

6. Complete Usage Examples

  • Basic configuration loading
  • Full-featured hot-reload example
  • Hot-reload callback patterns

7. Environment Variable Reference

  • All UNIFIED_* environment variables documented

8. YAML Configuration Examples

  • Minimal, production, and environment-substitution examples

9. Hot-Reload Patterns

  • Selective hot-reload
  • Validation before apply

10. Troubleshooting

  • Common errors and solutions

Test Plan

  • Documentation follows existing style (INTEGRATION_GUIDE.md)
  • All 7 configuration sub-structs documented
  • All 4 header files covered
  • Complete usage examples provided
  • Environment variable reference included
  • YAML examples provided
  • Hot-reload patterns documented
  • Troubleshooting section added

Related Files

  • include/kcenon/common/config/config_watcher.h
  • include/kcenon/common/config/unified_config.h
  • include/kcenon/common/config/cli_config_parser.h
  • include/kcenon/common/config/config_loader.h

Add comprehensive documentation for the configuration subsystem including:
- Configuration architecture and source priority
- Unified config schema with 7 sub-structs
- Config watcher with cross-platform file system monitoring
- CLI config parser for command-line arguments
- Config loader with YAML support and validation
- Complete usage examples and hot-reload patterns
- Environment variable reference and YAML examples
- Troubleshooting guide

Closes #326
@kcenon kcenon merged commit 5c4e9bc into main Feb 8, 2026
24 checks passed
@kcenon kcenon deleted the docs/issue-326-document-configuration-subsystem branch February 8, 2026 08:31
kcenon added a commit that referenced this pull request Apr 13, 2026
Add comprehensive documentation for the configuration subsystem including:
- Configuration architecture and source priority
- Unified config schema with 7 sub-structs
- Config watcher with cross-platform file system monitoring
- CLI config parser for command-line arguments
- Config loader with YAML support and validation
- Complete usage examples and hot-reload patterns
- Environment variable reference and YAML examples
- Troubleshooting guide

Closes #326
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Task] docs: Document configuration subsystem (config_watcher, unified_config, cli_config_parser)

1 participant