jsh9 / pydoclint

A Python docstring linter that checks arguments, returns, yields, and raises sections
https://pypi.org/project/pydoclint/
MIT License
151 stars 15 forks source link

Add a feature to check exceptions (name and order) #158

Closed jsh9 closed 2 months ago

jsh9 commented 4 months ago

This is mentioned in: https://github.com/astral-sh/ruff/issues/458#issuecomment-2236915256

@jsh9 I don't think those check the exception types. For example, if I have a function like this, which sometimes raises a ValueError, but incorrectly document that it raises a ZeroDivisionError, darglint will report the problem while pydoclint won't:

def _str_to_bool(informal_bool: str) -> bool:
    """
    Translate a commonly used boolean ``str`` into a real ``bool``.

    Args:
        informal_bool: A boolean represented as ``str``, like ``"true"``, ``"no"``, ``"off"``, etc.

    Returns:
        ``True`` or ``False`` to match the intent of ``informal_bool``.

    Raises:
        ZeroDivisionError: This doesn't look like enough like a ``bool`` to translate.
    """
    if informal_bool.lower() in ('true', 't', 'yes', 'y', 'on', '1'):
        return True
    if informal_bool.lower() in ('false', 'f', 'no', 'n', 'off', '0'):
        return False
    raise ValueError(f"{informal_bool} doesn't look like a boolean")  # pragma: no cover
$ darglint nt2
nt2/casters.py:_str_to_bool:29: DAR401: -r ValueError
nt2/casters.py:_str_to_bool:39: DAR402: +r ZeroDivisionError

$ pydoclint nt2
Loading config from user-specified .toml file: pyproject.toml
No config found in pyproject.toml.
Skipping files that match this pattern: \.git|\.tox
nt2/__init__.py
nt2/casters.py
nt2/converters.py
nt2/dumpers.py
nt2/ui.py
nt2/yamlpath_tools.py
🎉 No violations 🎉