| name | doc-audit |
| description | Dedicated documentation work — OKF format, topical audits, extract-overview and inline-doc workflows |
Documentation System
Two layers, built bottom-up:
README.md per folder
- No frontmatter — it's an index, not a concept
- 1-3 sentences: what this folder contains
- Bullet list of key files/subfolders with one-line descriptions
- Build from folders you're working in, not top-down
Topical Audit (doc/TopicalAudit/)
Cross-language maps connecting implementations of the same scientific topic. One file per topic.
---
type: TopicalAudit
title: <Topic Name>
tags: [topic, cross-language]
---
Body:
- Summary: 1 paragraph
- Implementations: table
Language | Location | Status | Notes
- Parity Status: verified pairs, tolerance, test reference
- Open Issues: TODOs, unported features
Status values: active, experimental, deprecated, unfinished.
OKF Principles
- Markdown + YAML frontmatter, no tooling required
- Frontmatter:
type (required), title, description, tags, timestamp (optional)
- Cross-link with markdown links (absolute
/path/to.md preferred)
- Structural markdown (headings, lists, tables, code blocks) over freeform prose
Extract Documentation Workflow
Generate concise human-readable overview from source files:
- Scope: one cohesive unit (single file or file+header pair)
- Read: skim imports, structure, function bodies for algorithmic essence
- Compose: Background (3-8 sentences), File/Class Summary, Functions (one-liner per function — purpose only, no args/returns), Tutorial (CLI flags / GUI controls / library snippet), Notes & Pitfalls
- Discover usage: detect argparse/main for CLI, check
*.sh for run commands, find event bindings for GUI
- Validate: run with small inputs if feasible; avoid full API dumps
Inline Documentation Workflow
Insert concise standardized comments into code:
- C/C++/OpenCL:
/// one-liners (Doxygen); avoid /* */
- Python: single-line docstrings
"""One-line summary"""
- File header: 1-3 sentences background + AUTO-DOC markers
- Functions: one-line
@brief above definition (C++) or docstring inside (Python)
- AUTO-DOC markers:
/// === AUTO-DOC BEGIN === / /// === AUTO-DOC END === (C++), # === AUTO-DOC BEGIN === / # === AUTO-DOC END === (Python) — allows safe regeneration
- Never delete existing comments; keep both if conflicting, mark new as AUTO-DOC
- No parameter/return enumeration unless critical; focus on purpose and essence
- Minimal edits — don't refactor while documenting
Writing Style: Essence Over Obvious
The goal of documentation is to convey what a reader cannot easily see from the code.
Stating the obvious is lazy — documentation should contain high-context background,
motivation, design rationale, and highlights that capture the essence of the file.
What to Write
- Essence: What is this file for, at the highest level? One sentence that a new
contributor can understand without reading the code. Example: "Fast function
approximations for hot loops in physics simulations" — not "Math utility functions."
- Motivation: Why does this file exist? What problem does it solve that the
alternatives (std::unordered_map, naive approach, library X) don't? Example:
"Open addressing with linear probing — unlike std::unordered_map's linked lists,
this keeps probe sequences cache-friendly for spatial hash tables."
- Design decisions and trade-offs: What were the choices, and why this one?
Example: "Power-of-2 batch size so division becomes bit-shift — faster on
architectures without hardware divide."
- Non-obvious algorith, desing decision and principle: Things that would surprise someone reading
the code. Example: "hits[] array tracks collision count per slot so getAllInBox()
can stop early — this is the key optimization over naive open addressing."
- Use cases: Where is this actually used in the engine? Example: "Used as
edgesOfVerts in Builder2 for O(1) 'which edges touch vertex i?' queries."
- Background/context: Algorithmic or mathematical context that informs the design.
Example: "Same principle as NEB/string methods in molecular dynamics, applied here
to geometric implicit surfaces."
What NOT to Write
- Obvious restatements of code: "This file defines a HashMap class" — the reader
can see that. Instead: "Open-addressing hash map optimized for integer box-index keys
in spatial bucketing."
- Parameter/return type listings: Unless critical for understanding, skip them.
The code already shows types. Focus on purpose, not signature.
- Empty formalities: "This file provides various utility functions for..." — say
what the utilities are for and why they're here, not that they exist.
- Fluff and filler: "This powerful and flexible module..." — adjectives are noise.
Describe what it does, not how impressive it is.
- Tutorial-style walkthroughs: The header doc is not a tutorial. It's context for
someone who is about to read or modify the code.
Format Rules
- Use
/// Doxygen style for C/C++ headers (not /* */)
- Start with
/// @file filename.h then /// @brief <one-sentence essence>
- Follow with
/// paragraphs for: motivation, design decisions, key functions/structs,
use cases, background — only the ones relevant to this file
- Use
**bold** for key terms and struct/function names within the doc
- Use
- bullet lists for enumerating design choices or key functions
- Keep total header doc to 10-25 lines — dense, not verbose
- Every sentence must carry information that is NOT visible in the code
README.md Style
- One bullet per file in the folder
- Each bullet: filename.h — one-sentence essence, then comma-separated key details
- No frontmatter, no headings beyond the folder name
- Order: most important/foundational files first, implementation files last
- Include .cpp files — they get a one-liner saying what they implement
Examples
Good @brief:
Open-addressing hash map for spatial bucketing — optimized for box-indexed lookups.
Bad @brief:
A hash map data structure.
Good body excerpt:
Unlike std::unordered_map (separate chaining with linked lists), this uses open
addressing with linear probing. The key insight: this map is designed for spatial
hash tables where the key is a cell/box index (integer), not an arbitrary object.
Bad body excerpt:
This class provides methods for inserting, removing, and finding elements in a
hash table. It supports generic types through templates.
Related Skills
doc-read-navigate — check existing implementations before writingdoc-task-summary — quick doc updates after implementation
