Doc Comment Writer

Add doc comments that help the next developer understand purpose, contract, constraints, and non-obvious decisions at the point of use. Prefer comments that save future readers from reconstructing intent; skip comments that merely paraphrase names, types, or straightforward control flow.

Workflow

1. Establish scope and comment style.

• Read the mentioned files first.
• Infer the language's normal doc comment form and follow the file's existing style.
• Inspect nearby types, tests, callers, or sibling files only when needed to understand public behavior or an important invariant.

2. Decide what actually needs documentation.

• Consider a file-level comment first when a file has a real module-level responsibility, boundary, or usage pattern that is not obvious from the filename and exports alone.
• Prioritize exported APIs, public modules, extension points, non-obvious helpers, and code with important invariants or tradeoffs.
• Add comments where a future reader would otherwise need to inspect internal logic to answer "what is this for?" or "what must stay true?"
• If a symbol is already obvious from its name, signature, and surrounding code, leave it undocumented.
• If a file does not need new doc comments, say so instead of forcing low-value edits.

3. Write for future readers, not for the current diff.