astral-sh / ruff

An extremely fast Python linter and code formatter, written in Rust.
https://docs.astral.sh/ruff
MIT License
33k stars 1.1k forks source link

Extend `docstring-missing-exception` to empty exception description (`DOC501`) #14494

Open sbrugman opened 2 days ago

sbrugman commented 2 days ago

The rule that checks missing documentation for parameters considers empty descriptions as undocumented (undocumented-param, DOC501). We have a similar rule for exceptions, which considers empty descriptions as documented (docstring-missing-exception, D417).

This example only errors for DOC501:

def func1(arg1: str, arg2: int) -> int:
    """

    Args:
        arg1:
        arg2:

    Raises:
        ValueError:
    """
    try:
        return int(arg1) + arg2
    except:
        raise ValueError("msg")
 ruff check --select D417,DOC501 --preview example.py

Proposal: modify D417 to report an error for empty exception descriptions.

Alternative solution: split undocumented and empty/missing into two separate rules.

This behaviour is especially useful when docstring stubs are auto-generated (https://github.com/astral-sh/ruff/issues/14492)