Skip to content

The Code-to-Docs Bridge

Code and documentation are maintained by separate teams. The @code-change tag in API documentation (Doxygen annotations or Python docstrings) is the bridge.

Tag Format

@code-change YYYY-MM-DD "free-text description of what changed and why"
  • Date: mandatory, ISO 8601 date only
  • Description: mandatory, double-quoted, one line

Placement

C/C++ (Doxygen)

Modified function

Add inside the existing Doxygen block:

/** @brief One-line purpose.
 *  @param[in] x  Input value.
 *  @see related_function [card-ID]
 *
 *  @code-change 2026-03-28 "Rewritten loop to use BLAS dcopy for stride-1 case"
 */

New function (no Doxygen block yet)

Create a stub:

/** @brief (new, undocumented)
 *  @code-change 2026-03-28 "New function: computes adaptive relaxation"
 */

Deleted function

Add to a calling function's block or file-level comment:

/* @code-change 2026-03-28 "Removed old_function -- replaced by new_function" */

Multiple changes accumulate

/** @brief ...
 *  @code-change 2026-03-20 "Changed threshold from 1e-20 to 1e-16"
 *  @code-change 2026-03-28 "Added early exit for zero-row case"
 */

Python (Sphinx reST docstrings)

Modified function

Add at the end of the existing docstring:

def solve(A, b):
    """Forward solve Ax = b.

    :param A: Coefficient matrix.
    :type A: scipy.sparse.csc_matrix
    :param b: Right-hand side.
    :type b: numpy.ndarray

    @code-change 2026-03-28 "Rewritten loop to use vectorized operations"
    """

New function (no docstring yet)

Create a stub docstring:

def new_function(x):
    """(new, undocumented)

    @code-change 2026-03-28 "New function: compute adaptive relaxation"
    """

Deleted function

Add to a calling function's docstring:

def caller(x):
    """...existing docstring...

    @code-change 2026-03-28 "Removed old_function -- replaced by new_function"
    """

Multiple changes accumulate

def solve(A, b):
    """Forward solve Ax = b.

    :param A: Coefficient matrix.
    :type A: scipy.sparse.csc_matrix

    @code-change 2026-03-20 "Changed threshold from 1e-20 to 1e-16"
    @code-change 2026-03-28 "Added early exit for zero-row case"
    """

Rules for code-developer (writer)

  1. Always add a tag when modifying function logic, signatures, constants, or control flow. Cosmetic changes (whitespace, comments) do not need a tag.
  2. One tag per logical change.
  3. For new source files, add a row to INDEX.md (Card = ---) and a file-level tag.
  4. For deleted source files, add tags to any file that called the deleted functions.

Rules for kb-developer (consumer)

  1. Read the @code-change description.
  2. Read the current source code.
  3. Update card, API docs (Doxygen or docstrings), and math doc as needed.
  4. Remove the @code-change line from the source file.
  5. Add a SYNCLOG entry (UPDATED or VERIFIED).
  6. Process all accumulated tags in one pass — update to current state.

Rules for kb-reviewer (detector)

  1. Scan source files for @code-change tags.
  2. Each pending tag lowers the Freshness score.
  3. Report pending tags in the board.

Git-Based Fallback

If code-developer forgets to add a tag, kb-reviewer detects via git:

  • Compare source file's last commit date vs last SYNCLOG date.
  • If source modified 7+ days after last doc sync with no tag: flag as SILENT-STALE.
  • Report with git diff summary so kb-developer can update without the tag.