Skip to main content
Version: v0.3.0

Documentation coverage plan

This document is a concrete plan for maintaining a documentation site with maximum coverage of SydraDB’s repository contents, with a bias toward:

  • Explaining every definition (functions, structs/enums/unions, variables, constants) in source modules
  • Capturing invariants, ownership/lifetimes, and error semantics (not just summaries)
  • Keeping docs navigable via crosslinks and a stable information architecture

This plan assumes docs live in docs/ (Docusaurus) and content lives in docs/docs/.

1) Scope rules (what “every file” means)​

In scope​

  • Runtime and library code: src/**
  • CLI tools: cmd/**
  • Examples: examples/**
  • Tests and fixtures: tests/**
  • Repo/build/tooling/config: build.zig, flake.nix, .github/**, .pre-commit-config.yaml, etc.

Out of scope (generated/ephemeral)​

These change across machines/builds and should not be documented line-by-line:

  • docs/node_modules/**, docs/.docusaurus/**, docs/build/**
  • Zig caches like **/.zig-cache/**, **/.zig-local-cache/**
  • OS/editor detritus (.DS_Store, etc.)

If any of the above accidentally land in the repo, treat them as cleanup items rather than documentation targets.

2) Information architecture (where docs go)​

Narrative docs​

Use these sections for human-oriented explanations:

  • getting-started/** — quickstart and operational usage
  • concepts/** — terminology and design intent
  • architecture/** — system-level design and invariants
  • reference/** — user-facing contracts (CLI flags, HTTP API, on-disk formats)
  • development/** — contributor workflows, CI, and documentation process

Source reference (line-by-line code mapping)​

The “Source Reference” section should mirror the repository tree at a module level under:

  • docs/docs/reference/source/**

Guidelines:

  • One doc per meaningful file/module (e.g. src/sydra/query/parser.zig → reference/source/sydra/query/parser.md)
  • Keep doc IDs stable; prefer renaming the doc file to match code renames as part of the same change
  • Prefer autogenerated sidebar structure for this section so new files don’t require sidebar edits

3) Coverage workflow (how to “go through every line”)​

Step A — Create/refresh an inventory​

Maintain a simple inventory list in docs (choose one):

  • a markdown table checked into docs/docs/development/ (good for reviews), or
  • a CSV under docs/ (good for sorting/filtering)

Minimum fields:

  • path (repo-relative)
  • doc_id (Docusaurus doc id)
  • owner_area (storage/query/codec/compat/build/etc.)
  • status (stub, draft, reviewed, needs-update)
  • notes (missing invariants, missing examples, etc.)

Step B — Document each file using a consistent template​

For each source file, read it top-to-bottom and capture:

  1. Purpose — what the module owns and what it explicitly does not own
  2. Key imports/dependencies — and why they matter (crosslink to their docs)
  3. Definition index — every public definition (pub const, pub var, pub fn, public types)
  4. Key behaviors — algorithms, invariants, and edge cases
  5. Error semantics — error sets, error unions, and which errors are user vs. internal
  6. Ownership/lifetimes — who allocates/frees; which slices are borrowed vs. owned; buffer reuse rules
  7. Performance notes — complexity, materialization points, hot paths, and any “known limitations”
  8. Code excerpts — small, accurate excerpts for critical semantics (prefer excerpts over copying entire files)
  9. See also / Used by — link to upstream/downstream modules and related narrative docs

Step C — Validate crosslinks and build​

Quality bar for “reviewed”:

  • npm run build succeeds with onBrokenLinks: "throw"
  • No obvious stale docs (function/type names match the code)
  • The module’s public surface is fully documented
  • Critical invariants and lifetimes are stated plainly (especially for storage/query)

4) Page template (recommended)​

Use this skeleton for new source reference pages:

  1. Title: `path/to/file.zig`
  2. ## Purpose
  3. ## See also and/or ## Used by
  4. ## Definition index (public) — list public types/constants/functions
  5. ## Key behaviors (as implemented) — the “why” and “how”
  6. ## Ownership and lifetimes
  7. ## Error model
  8. ## Code excerpt — keep excerpts small and correct

Consistency matters more than perfection; prefer incremental improvements over rewrites.

  • Prefer linking to docs pages (module docs) over linking to GitHub line anchors.
  • Use relative links between docs in the same tree (./parser.md, ../engine.md) so versioned docs work cleanly.
  • When you must reference repository files directly, use repo-relative code paths (e.g. src/sydra/engine.zig) and keep them in backticks.

6) Ongoing maintenance (keep docs in sync)​

Add a lightweight PR checklist (for contributors) for changes that impact docs:

  • New public symbol or behavior change → update the corresponding reference/source/** page
  • New runtime flag → update reference/configuration.md and sydradb.toml.example
  • New HTTP endpoint → update reference/http-api.md
  • New on-disk format change → update reference/on-disk-format.md
  • New directory/module → add or move the matching source reference page

7) Optional: automation ideas (docs-only)​

If manual upkeep becomes too costly, consider adding docs-only tooling under docs/:

  • A script that inventories repo files and highlights missing reference/source/** pages
  • A “stub generator” that creates placeholder pages for new files with the standard template
  • A small checker that ensures every pub symbol appears in the definition index (best-effort)

Keep generated output human-editable; the goal is acceleration, not replacing review.