undocumented-param (D417)#
Derived from the pydocstyle linter.
What it does#
Checks for function docstrings that do not include documentation for all parameters in the function.
Why is this bad?#
Multi-line docstrings are typically composed of a summary line, followed by a blank line, followed by a series of sections, each with a section header and a section body.
Function docstrings often include a section for function arguments, which should include documentation for every argument. Undocumented arguments are indicative of missing documentation.
This rule is enabled when using the google convention, and disabled when
using the pep257 and numpy conventions.
Example#
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Args:
distance: Distance traveled.
Returns:
Speed as distance divided by time.
Raises:
FasterThanLightError: If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc
Use instead:
def calculate_speed(distance: float, time: float) -> float:
"""Calculate speed as distance divided by time.
Args:
distance: Distance traveled.
time: Time spent traveling.
Returns:
Speed as distance divided by time.
Raises:
FasterThanLightError: If speed is greater than the speed of light.
"""
try:
return distance / time
except ZeroDivisionError as exc:
raise FasterThanLightError from exc