> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackra.figentra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 0007 — Source documentation standard

> Accepted, amended by 0128 · 2026-10-19

> [!NOTE]
>
> Amended by [0128](/adr/0128-code-conventions-enums-classes-components-and-kind-folders): the
> documentation rules for classes and members are assumed there, pending the owner.

## Context

Agents and new contributors read files cold. The cheapest durable defence against a wrong change is a header that says
what the file is for and which rule governs it. Doc comments that restate a signature are noise and teach readers to skip comments.

## Decision

1. **Every source file opens with a contract block** before its imports:

   * `Purpose:` what the file is for.
   * `Boundary:` what it declares and what it does not own.
   * `Runtime:` one of `node`, `browser`, `worker`, `react-native`, `isomorphic`.
   * `Governing contract:` the ADR or standard a change must respect.

   Non-TypeScript files (JSON with comments, YAML, shell, `.mjs`) carry the same fields in their own comment syntax. The
   repository's own config files already do this (`# Stackra file contract:`).

2. **Every exported symbol has TSDoc that says something the type does not**: a purpose sentence always; `@param` and
   `@returns` when meaning, units or ownership are not in the type; `@throws` for each error a caller must handle; `Side effects:`
   for I/O and global mutation; `Invariant:`; `@example` when use is not obvious; `@deprecated` with replacement and removal target.

3. **Types carry the weight first.** No `any`; generics get meaningful names; an exported type is its own documentation.

4. **Boilerplate is a finding.** A comment restating the signature fails review.

## Consequences

* Reading cost per file drops; writing cost rises by a few lines.
* `/standards/code-style` is the operating form (header fields, tags, examples).

## Enforcement

Planned: a doc-standard check in `tools/scripts` (port basalt `doc-standard.mjs`) that requires the header and TSDoc on
exports and runs in `pnpm validate`. Until then headers exist by convention, as in `lefthook.yml`, `turbo.jsonc` and `pnpm-workspace.yaml`.

## Supersedes and sources

Supersedes: none. Sources: basalt `adr/0011-documentation-and-source-comment-standard`; figentra `docs/constitution/documentation.md`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.