From 8f400bb37abfc625e0338041a9816bd6d4f79e66 Mon Sep 17 00:00:00 2001
From: GiGaGon <107241144+MeGaGiGaGon@users.noreply.github.com>
Date: Wed, 9 Jul 2025 09:59:31 -0700
Subject: [PATCH] [`pydoclint`] Make example error out-of-the-box (`DOC501`)
 (#19218)

<!--
Thank you for contributing to Ruff/ty! To help us out with reviewing,
please consider the following:

- Does this pull request include a summary of the change? (See below.)
- Does this pull request include a descriptive title? (Please prefix
with `[ty]` for ty pull
  requests.)
- Does this pull request include references to any relevant issues?
-->

## Summary

<!-- What's the purpose of the change? What does it do, and why? -->

Part of #18972

This PR makes [docstring-missing-exception
(DOC501)](https://docs.astral.sh/ruff/rules/docstring-missing-exception/#docstring-missing-exception-doc501)'s
example error out-of-the-box. Since the exceptions in the function body
need to undergo name resolution to figure out if one of them is
`NotImplementedError`, `DOC501` won't lint if the raised name is not
defined. This could be considered a limitation, but should be fine since
`F821` already covers undefined names. I did discover a different edge
case, but it's not relevant to the example.

[Old example](https://play.ruff.rs/d213e87d-e5c7-49d8-a908-931f61f06055)
```py
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.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc
```

[New example](https://play.ruff.rs/cb41e0b7-b950-4fa0-842d-cecab9c8e842)
```py
class FasterThanLightError(ArithmeticError): ...


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.
    """
    try:
        return distance / time
    except ZeroDivisionError as exc:
        raise FasterThanLightError from exc
```

The "Use instead" section was also updated similarly.

## Test Plan

<!-- How was it tested? -->

N/A, no functionality/tests affected
---
 .../src/rules/pydoclint/rules/check_docstring.rs            | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs b/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs
index f815258da2..1f5f5a0763 100644
--- a/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs
+++ b/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs
@@ -238,6 +238,9 @@ impl Violation for DocstringExtraneousYields {
 ///
 /// ## Example
 /// ```python
+/// class FasterThanLightError(ArithmeticError): ...
+///
+///
 /// def calculate_speed(distance: float, time: float) -> float:
 ///     """Calculate speed as distance divided by time.
 ///
@@ -256,6 +259,9 @@ impl Violation for DocstringExtraneousYields {
 ///
 /// Use instead:
 /// ```python
+/// class FasterThanLightError(ArithmeticError): ...
+///
+///
 /// def calculate_speed(distance: float, time: float) -> float:
 ///     """Calculate speed as distance divided by time.
 ///