Source documentation policy

Step 59 makes the source tree suitable for publication as technical reference material. The goal is useful Doxygen coverage, not comments that merely restate syntax.

What is documented

Every .h and .cpp carries @file, @brief and subsystem @ingroup metadata. Named classes, structs and enums in public project headers have Doxygen descriptions. Callable declarations in project headers are documented including private non-trivial helpers, because these helpers often encode important numerical or GUI invariants. Translation-unit-local helper functions are documented at their definitions.

The central numerical classes receive additional model/method explanations and are linked to the architectural pages in this manual.

What is intentionally not documented line-by-line

Automatic comments such as ++i; // increment i reduce readability and add no knowledge. Local loop variables and obvious implementation temporaries are therefore described by normal code context rather than forced Doxygen entries. Doxygen documents the contract and intent of a function/type; ordinary inline comments explain a mathematically non-obvious implementation step.

Change discipline

When a signature changes, update its Doxygen block in the same commit. When a new subsystem is introduced, assign it to one of the existing groups or add a new documented group. validate_doxygen_sources.py should remain green before a release checkpoint is packaged.