documentation-style

Standardize Rust documentation by enforcing a mandatory Why, What, and Test structure for all public artifacts. This ensures every doc comment provides high-density, context-efficient information by clearly stating motivation, mechanical behavior, and test coverage.

The Why/What/Test model is a documentation structure that requires public functions to explicitly state their motivation, mechanical behavior, and corresponding test coverage. It prevents documentation bloat by focusing on contracts rather than implementation details.

Prevent documentation bloat in API design by applying context-economy principles that focus on contracts rather than implementation details. This keeps information high-density and context-efficient, reducing cognitive load for both developers and AI agents.

Spec-linked documentation works effectively with code reviews by enforcing the four-axis model across all public artifacts. Reviewers can verify that modules clearly state their motivation, mechanical behavior, and test coverage.

This documentation style guide applies to software engineering workflows including code reviews, API design, and module-level documentation. While it references Rust modules, the four-axis model and spec-linked conventions can standardize documentation across any codebase.

Context-economy principles should not be used when implementation details are critical to understanding the artifact. This approach focuses on contracts to prevent bloat, so avoid it when step-by-step implementation context is required.