Contributing#

Documenting C Code#

semicolon-lapack uses Doxygen-style comments that are processed by Breathe into Sphinx documentation.

Comment Style#

Use Javadoc-style comments with @param:

/**
 * Brief description (first sentence ends with period).
 *
 * Detailed description can span multiple paragraphs.
 *
 * @param[in]     m     Number of rows of matrix A (m >= 0)
 * @param[in]     n     Number of columns of matrix A (n >= 0)
 * @param[in,out] A     On entry, the M-by-N matrix A.
 *                      On exit, the factors L and U from A = P*L*U.
 * @param[in]     lda   Leading dimension of A (lda >= max(1,m))
 * @param[out]    ipiv  Pivot indices, dimension min(m,n). Row i was
 *                      interchanged with row ipiv[i].
 * @param[out]    info  = 0: successful exit
 *                      < 0: if -i, the i-th argument had an illegal value
 *                      > 0: if i, U(i,i) is exactly zero
 */
void dgetrf(const int m, const int n, double* const restrict A,
            const int lda, int* const restrict ipiv, int* info);

Parameter Direction#

Always specify parameter direction:

  • @param[in] — Input only, not modified

  • @param[out] — Output only, input value ignored

  • @param[in,out] — Both input and output

Building Documentation#

The documentation pipeline uses Doxygen (C) and Sphinx (Python), connected by the Breathe extension. You will need:

These are also listed in doc/requirements.txt for convenience:

pip install -r doc/requirements.txt

(or conda, uv or whichever tool you use)

Then build and serve locally:

cd doc
make html
cd build/html && python -m http.server 8000

The output will be in doc/build/html/ and served at http://localhost:8000.

Note

If you prefer Doxygen’s native HTML output (no judgement), you can run doxygen doc/source/Doxyfile directly and skip the Python toolchain entirely. We specifically avoid the caller diagrams and source browser that Doxygen generates. There is no technical reason, we just don’t like them.