mxlib Documentation Standards

how to document mxlib code

Documenting mxlib Code

mxlib uses doxygen.

Documenting Tests

mxlib uses the Catch2 unit testing framework.

To document a test and link it to the production API being tested:

1. Use a Catch2 TEST_CASE for each top-level test.
2. Put a brief Doxygen summary immediately before the TEST_CASE whose text exactly matches the Catch2 test name. Put any additional production-API and behavior detail in the following documentation block.
3. Put each TEST_CASE in its production component's leaf unit-test group, such as String Utilities Unit Tests.
4. Call the production API directly in the test body so Doxygen can add the test to the API's Referenced by list.
5. If a fixture, wrapper, or macro hides the production call, add a reference-only call guarded by #ifdef __DOXY_ONLY__.
6. Ensure the directory containing the test source is included in mxlib_doxygen.in.
7. For a header-only class-template placeholder, explicitly instantiate an unambiguous supported specialization in a Doxygen-hidden block so non-template member bodies are compile checked and can emit coverage counters. Do not duplicate a specialization already owned by a production translation unit, and do not present this compile check as a behavioral assertion.
8. Keep Catch2 assertions in the TEST_CASE or SECTION body. Shared helpers should return named comparison values and tolerances for local assertion rather than an opaque boolean. Use CAPTURE or INFO to retain loop and backend context in failure reports.