Doc Comment Writer

Curate durable doc comments that help future maintainers understand purpose, contract, constraints, and non-obvious decisions without reconstructing them from implementation. A restatement merely paraphrases names, types, or straightforward control flow; omit it.

Workflow

1. Establish scope and local conventions.

   • Follow the user's stated scope. Infer the language's normal doc comment form and the file's existing style and comment density.
   • Inspect nearby types, tests, callers, or sibling files only when needed to understand public behavior or an important invariant.
   • Continue once the files and symbols in scope and their applicable comment syntax and style are clear.

2. Make an explicit keep, change, or skip decision.

   • Consider a file-level comment when the file has a responsibility, boundary, or usage pattern that is not obvious from its name and exports.
   • Add comments where a future reader would otherwise need to inspect internal logic to answer "what is this for?" or "what must stay true?"
   • Retain an existing comment only when removing it would lose reader-relevant information. Revise stale or unclear comments and remove comments that merely narrate the declaration or implementation.
   • Leave symbols undocumented when their names, signatures, types, and context already answer those questions. If the file needs no new comments, say so instead of forcing edits.
   • Continue once every exported or public symbol and existing doc comment in scope, plus any relevant file header, has an explicit retain, add, revise, remove, or skip decision.