Skip to content

undocumented-public-function (D103)#

Derived from the pydocstyle linter.

What it does#

Checks for undocumented public function definitions.

Why is this bad?#

Public functions should be documented via docstrings to outline their purpose and behavior.

Generally, a function docstring should describe the function's behavior, arguments, side effects, exceptions, return values, and any other information that may be relevant to the user.

If the codebase adheres to a standard format for function docstrings, follow that format for consistency.

Example#

def calculate_speed(distance: float, time: float) -> float:
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc

Use instead (using the NumPy docstring format):

def calculate_speed(distance: float, time: float) -> float:
    """Calculate speed as distance divided by time.

    Parameters
    ----------
    distance : float
        Distance traveled.
    time : float
        Time spent traveling.

    Returns
    -------
    float
        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

Or, using the Google docstring format:

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

Options#

References#