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
- 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.
- 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.
- Write for future readers, not for the current diff.
- Explain what the symbol does at a useful level of abstraction.
- Explain inputs, outputs, side effects, failure modes, lifecycle expectations, or invariants when they matter.
- Capture why a boundary exists, what a caller can rely on, and what would be easy to misuse.
- Mention tradeoffs or intentionally surprising behavior when that context will age well.
- Avoid describing step-by-step implementation details that will go stale after a refactor.
- Keep comments lean and local.
- Keep file-level comments short and structural: explain the file's role, boundaries, or why related pieces live together.
- Prefer one strong doc comment over several weak inline comments.
- Keep wording tight; use full sentences only when they carry real information.
- Preserve existing formatting and keep edits close to the symbols they describe.
- Use inline comments only when a local invariant or subtle branch needs explanation beyond what a doc comment can carry.
- Check the result against a high bar.
- Remove comments that only restate the name, type, or obvious return value.
- Remove generic filler such as "Helper function" or "Represents X" unless the next sentence adds real contract information.
- Ensure each new comment would still be useful if the reader never opened the function body.
- If you had to infer behavior from code rather than an explicit contract, phrase the comment conservatively.
Writing Rules
- Prefer purpose, contract, invariants, and caller-relevant behavior.
- Use file-level comments only when they add context the exports and naming do not already provide.
- Omit obvious information the code already makes clear.
- Do not narrate internal control flow.
- Do not speculate about intent when the code does not support it.
- Do not document every symbol for symmetry; document the ones that benefit from it.
- Match the repository's tone and comment density.
Good Targets
- File or module headers that explain responsibility, boundaries, integration points, or how to approach the file.
- Public functions whose names are clear but whose guarantees, side effects, or failure behavior are not.
- Types whose fields are simple but whose semantic meaning or lifecycle needs explanation.
- Internal helpers only when they encode a tricky invariant, protocol, or normalization rule.
Poor Targets
- File headers that only restate the filename or say the file "contains utilities" without sharper guidance.
- Trivial getters, setters, and one-line wrappers with obvious names.
- Comments that duplicate parameter names or type annotations.
- Comments that only describe how a loop or conditional works.
- Large doc blocks copied from implementation details.
Response Expectations
- Edit the mentioned files directly when the user asked for code changes.
- Keep the diff focused on documentation unless the user also asked for refactors.
- After editing, briefly report any file-level comments you added, what symbols you documented, what you intentionally left undocumented, and any places where the code itself remained too unclear to document confidently.