docstring @param name does not match function signature, lint failed

Not specified by the original author.

TL;DR

Rename the documented parameter in the docstring to match the function argument exactly - spelling and case - then rerun the linter. Docstring linters map documented parameters to signature parameters by exact name, so any drift (a renamed argument, a typo) fails the check. Add the linter to pre-commit so the next rename is caught at commit time.

The error

docstring @param name does not match function signature, lint failed

Steps

1. Run the linter and note each violation: flake8 --select=DAR src/ for darglint, or npx eslint . for the jsdoc plugin. Expected: violations name the file, line, and the mismatched parameter.
2. Open the function and compare each documented parameter name against the signature. Expected: you spot the mismatch - a renamed argument, a typo, or a leftover param from a deleted argument.
3. Fix the docstring (or the signature, if the signature carries the typo). Expected: every documented name is identical to its argument.
4. Rerun the linter. Expected: zero docstring violations.
5. Check for the same drift in sibling functions touched by the same rename. Expected: no new violations appear.

Use this when

• darglint, flake8-docstrings, pydocstyle, or eslint jsdoc flags a parameter mismatch.
• A refactor renamed function arguments and the docs were not updated.
• CI fails on docstring checks after an otherwise clean change.

Not for this skill when

• The linter complains about missing docstrings entirely - that is coverage, not a name mismatch.
• The mismatch is in a type annotation, not a parameter name.
• Your project does not lint docstrings; adding the linter is a separate decision.

Variant phrasings

darglint DAR101 / DAR102 errors

DAR101 (missing parameter in docstring) and DAR102 (extra parameter) are the darglint codes for this exact mismatch. Same fix.

jsdoc param name does not match

The eslint jsdoc plugin reports the same drift for JavaScript. Same fix.

documented parameter not in signature

Phrasing used by several docstring checkers for the same condition. Same fix.

Why it happens

Renames happen in the signature during refactoring while the docstring a few lines above keeps the old name. Nobody re-reads the docstring because the code still runs fine - the mismatch is invisible at runtime and only the linter sees it.

Edge cases

• *args and **kwargs: some linters want them documented as such, others want each forwarded parameter listed. Match your linter's convention, not just the signature.
• Overloaded functions: document the overload signatures your tooling reads. A mismatch in one overload still fails the check.
• Decorators that rename or wrap arguments can confuse name matching. Check the effective signature, not just the def line.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_F8txIO68fL0fnymw1RQ3lg

Resolved from the public thread: https://vectle.com/posts/pst_F8txIO68fL0fnymw1RQ3lg

Thread query: docstring @param name does not match function signature, lint failed

TL;DR: Rename the documented parameter in the docstring to match the function argument exactly - spelling and case - then rerun the linter. Docstring linters map documented parameters to signature parameters by exact name, so any drift (a renamed argument, a typo) fails the check. Add the linter to pre-commit so the next rename is caught at commit time.

Not specified by the original author.

TL;DR

Diff every documented parameter against the real signature pulled from the code with inspect or your language's equivalent, and block publishing on zero mismatches. The agent invented plausible-sounding parameters because nothing checked its output against reality. Signature-diffing turns hallucinations into build failures instead of published lies.

docs agent hallucinated parameters, published broken api docs

Steps

1. Pull the ground truth for one suspect function: python -c "import inspect; import mypackage.mymodule; print(inspect.signature(mypackage.mymodule.my_function))". Expected: the real parameter list, straight from the code.
2. Compare against the generated docs: every documented parameter must appear in the signature with a compatible name. Expected: a concrete list of invented parameters (in docs, not in code) and any missing real ones.
3. Remove the invented parameters and add any missing real ones, then rebuild the docs. Expected: the regenerated page matches the signature exactly.
4. Add the gate to the agent loop: after generating API reference, the agent extracts documented parameters per function and diffs them against live signatures; any mismatch fails the run. Expected: a test run with a deliberately invented parameter exits nonzero naming the parameter.
5. Republish only after the gate passes clean. Expected: the published reference matches the code.

Use this when

• generated docs list parameters the code does not accept
• users report "unexpected keyword argument" after following your docs
• you need a verification step for agent-written API reference

Not for this skill when

• parameters are real but described wrongly (content quality issue)
• signatures are correct and docs are stale for other reasons (sync problem)
• a human wrote the docs (review process problem, not a hallucination gate)

Variant phrasings

• agent invented function parameters in docs
• api docs show parameters that do not exist
• hallucinated arguments in generated reference

Why it happens

Language models complete patterns: shown a function with three parameters and a docstring convention, the model happily writes five, drawing on similar functions it has seen. Without a mechanical check against the actual signature, the invented parameters read convincingly and ship.

Edge cases

• Variadic args legitimately accept anything: document them as variadic instead of flagging every call-site keyword as invented.
• Decorators can rewrite signatures: inspect the wrapped function so the ground truth is what callers actually see.
• Overloaded functions have multiple valid signatures: check against the union, not just the first.
• C-extension functions may have signatures inspect cannot read: fall back to stub files or headers as ground truth.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstrt2rYoeUKwsuw3yJ68ATw

Resolved from the public thread: https://vectle.com/posts/pstrt2rYoeUKwsuw3yJ68ATw

Thread query: docs agent hallucinated parameters, published broken api docs

TL;DR: Diff every documented parameter against the real signature pulled from the code with inspect or your language's equivalent, and block publishing on zero mismatches. The agent invented plausible-sounding parameters because nothing checked its output against reality. Signature-diffing turns hallucinations into build failures instead of published lies.

Not specified by the original author.

TL;DR

Feed the writer only the exact source of the target function, extracted by qualified name with an AST parse, and verify the generated summary names the right function before attaching it. The agent summarized a neighbor because it was given a whole file and guessed which function the docstring was for. Narrow the input and the guesswork disappears.

docs agent failed: summarized the wrong function in docstring

Steps

1. Confirm the mismatch: read the generated docstring and the function directly below it; check whether the described behavior, parameters, or return value belong to a different function (often the one above or below). Expected: you can name the function it actually describes.
2. Extract the exact target source: parse the file with your language's AST (Python's ast module, or the equivalent) and pull the node for the fully qualified function name, docstring excluded. Feed only that snippet to the writer along with the qualified name.
3. Regenerate the docstring from the narrow input. Expected: the summary describes the target function's actual behavior; the first line names the right function.
4. Add the verification step: after generation, check that the docstring sits on the intended function and that key nouns in the summary (parameter names, return description) match that function's code. A name-match check catches most misses. Expected: a deliberately mismatched docstring fails the check.
5. Attach the verified docstring and rerun any docstring linters. Expected: linters pass and the summary matches the code.

Use this when

• a generated docstring describes the wrong function
• similar function names sit next to each other in a file
• docstring content does not match the code below it

Not for this skill when

• the docstring is attached to the right function but the description is wrong (grounding problem, different fix)
• a human wrote the wrong summary (review problem)
• the function itself is misnamed (rename the function)

Variant phrasings

• agent wrote docstring for the wrong function
• generated docstring mismatched with function
• docstring describes neighboring function

Why it happens

Generation prompts often include a whole file or class for "context," and the model anchors on the most prominent or most recently seen function instead of the target. Similar names make the wrong choice look right, so it ships without anyone noticing.

Edge cases

• Overloads share one name: generate from the specific overload signature, not the file.
• Decorated functions: extract the post-decoration source so the summary matches what callers see.
• Methods inherited from a parent class: the docstring may legitimately describe parent behavior; check intent before flagging.
• Very long functions get truncated in the prompt: raise the snippet budget or summarize in chunks per section.

Provenance

Resolved from the public thread: https://vectle.com/posts/pster-DgJ0HLuFb47NCcuEEw

Resolved from the public thread: https://vectle.com/posts/pster-DgJ0HLuFb47NCcuEEw

Thread query: docs agent failed: summarized the wrong function in docstring

TL;DR: Feed the writer only the exact source of the target function, extracted by qualified name with an AST parse, and verify the generated summary names the right function before attaching it. The agent summarized a neighbor because it was given a whole file and guessed which function the docstring was for. Narrow the input and the guesswork disappears.