The Living Documentation: Verified Code Snippet Extraction from Tests

[teogor]

Description

Automates the maintenance of "Usage Examples" in README files by extracting verified code snippets directly from the project's unit tests or sample modules.

Problem Statement

Documentation examples are notorious for becoming outdated ("bit-rot"). A developer changes an API, forgets to update the README, and the next user gets a compilation error. This destroys trust in the library and increases support burden.

Proposed Solution

A system where developers mark blocks of code in their tests with special comments (e.g., // [winds:example:start]), and winds automatically injects these snippets into the module's README.md.

Key Benefits

• Guaranteed Correctness: Since the examples are part of the test suite, they MUST compile and pass for the documentation to be updated.
• Zero Redundancy: Developers don't have to copy-paste code between IDE and Markdown files.
• AI-Friendly: Provides AI agents with high-quality, verified usage patterns that are guaranteed to work in the current version.

Implementation Details

• Parser to scan src/test/kotlin for tagged blocks.
• Template engine to replace placeholders in README.md (e.g., <!-- winds:snippet:my-feature -->).
• Integration with windsGenerateReadme to ensure a unified documentation workflow.