Documentation Generation That Doesn't Restate the Code

// increments the counter by one above counter += 1 is the canonical output, and mocking it misses why it happens. Given only the code, a paraphrase is the most likely continuation. The fix is upstream of the prompt. Why it paraphrases Documentation is valuable exactly where it says something the code does not: why this exists, what it must never do, which invariant it upholds, what units the number is in, what happens on failure, what was tried first and rejected. None of that is recoverable from the source. A model given only the source and asked to document it has one available strategy, which is to restate. So the question is not how to prompt around it. It is where the intent is written down, and whether you can put that in the context. There is a second, quieter failure worth naming: documentation generated at the wrong altitude. Asked to document a module, a model will produce one paragraph per function, because functions are the structure it can see. What a reader needs from a module document is the opposite — what this module is responsible for, what it deliberately does not do, which of its exports are the entry points and which are incidental, and what you must not do to it. That shape has to be asked for explicitly, and it is the only shape at which a module document beats simply reading the code. Where intent is actually recorded More of it exists than people assume — it is simply not in the file. The history of the exact lines. The most useful single command in this whole area: git log -L :priceLineItems:src/billing/invoice.ts --format='%h %ad %s%n%b' Every commit that touched that one function, with its message. Where a team writes real commit messages this is a complete design history, and it is the single best thing to paste alongside the code. The pull request discussion. gh pr list --search "invoice locked" --state merged then gh pr view N --comments. Rejected alternatives live here and nowhere else, and “why not X” is the question documentation most often needs to answer. Test names. A suite is a specification written in the imperative. test_locked_period_rejects_backdated_invoice states a rule the implementation only implies. The deleted code. A guard that was added, removed and added again is a documented hazard; only the history shows the cycle. The issue tracker. Frequently the only record of the customer situation that caused the constraint. The prompt that surfaces the gap Before asking for a document, ask for the questions the code cannot answer. This inverts the failure: instead of confidently filling gaps with paraphrase, the model enumerates them and you fill them. Here is a module and the git log for its main functions. Do not write documentation yet. List every question a new maintainer would need answered that you cannot answer from what I have given you. For each, say what evidence would answer it. 1. What are the units of 'threshold'? (source: none — the type is number, callers pass both 30 and 30_000) 2. Is issueInvoice safe to retry? It writes then publishes; is the publish idempotent? (source: the consumer, not shown) 3. Why does resolveTaxRule special-case a missing vatId rather than rejecting? (source: the PR that added it, or a domain expert) Answer those five sentences and the subsequent generated document is worth reading, because you supplied the only part that was ever missing. This costs about two minutes and is the difference between documentation and decoration. What the difference looks like Abstract advice about “capturing intent” is easy to agree with and hard to act on, so here is the same function documented both ways. The first is what you get from the code alone; the second is what you get after two minutes of answering the questions above. /** Issues an invoice for the given organisation and period. * @param orgId the organisation id * @param period the billing period * @returns the created invoice */ //