[pydoclint] Extend docstring-missing-exception to empty exception descriptions (DOC501)

[sbrugman]

Summary

Resolves #14494.

Test Plan

cargo test. Awaiting ecosystem checks.

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

ℹ️ ecosystem check detected linter changes. (+2 -0 violations, +0 -0 fixes in 1 projects; 53 projects unchanged)

bokeh/bokeh (+2 -0 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --output-format concise --preview --select ALL

+ src/bokeh/client/util.py:41:5: DOC501 Raised exception `ValueError` missing from docstring
+ src/bokeh/client/util.py:68:5: DOC501 Raised exception `ValueError` missing from docstring

Changes by rule (1 rules affected)

code	total	+ violation	- violation	+ fix	- fix
DOC501	2	2	0	0	0

[MichaReiser]

Let's wait with merging this until after the 0.8 release

[sbrugman]

Bokeh is a false positive. They use google-style, but start exception descriptions on a newline.

[sbrugman]

Reference that newlines are valid after the colon in Google-style docstrings: https://google.github.io/styleguide/pyguide.html#doc-function-args

[MichaReiser]

Reference that newlines are valid after the colon in Google-style docstrings: google.github.io/styleguide/pyguide.html#doc-function-args

I'm now slightly confused. Doesn't that suggest that the Bokeh ecosystem results aren't a false positives?

[MichaReiser]

I noticed that we have D414 which explicitly flags empty sections.

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

    Args:

    Returns:

    Raises:
        ValueError:

    """
    raise ValueError
    return distance / time

Both the Args and Returns section are flagged by D414 but the ValueError isn't. Should we extend D414 to detect missing exception documentation instead?

I suspect that the counter-argument is that the rule also doesn't raise for arguments with missing documentation:

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

    Args:
        distance:
        time:

    Returns:

    Raises:
        ValueError:

    """
    raise ValueError
    return distance / time

[sbrugman]

I'm now slightly confused. Doesn't that suggest that the Bokeh ecosystem results aren't a false positives?

Bokeh has documentation, just on a new line which is valid according to the Google-style. No violation should be raised. There are two new ones.