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.

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.