[pydoclint] Implement docstring-missing-exception and `docstring-…

…extraneous-exception` (`DOC501`, `DOC502`) (#11471)

## Summary

These are the first rules implemented as part of #458, but I plan to
implement more.

Specifically, this implements `docstring-missing-exception` which checks
for raised exceptions not documented in the docstring, and
`docstring-extraneous-exception` which checks for exceptions in the
docstring not present in the body.

## Test Plan

Test fixtures added for both google and numpy style.

LICENSE

@@ -1371,3 +1371,28 @@ are:
     OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
     SOFTWARE.
   """
+
+- pydoclint, licensed as follows:
+  """
+    MIT License
+
+    Copyright (c) 2023 jsh9
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+  """

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC501_google.py

@@ -0,0 +1,192 @@
+import something
+from somewhere import AnotherError
+
+
+class FasterThanLightError(Exception):
+    ...
+
+
+_some_error = Exception
+
+
+# OK
+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
+
+
+# DOC501
+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
+
+
+# DOC501
+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
+    except:
+        raise ValueError
+
+
+# DOC501
+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:
+        print('oops')
+        raise exc
+
+
+# DOC501
+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, ValueError) as exc:
+        print('oops')
+        raise exc
+
+
+# DOC501
+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.
+    """
+    raise AnotherError
+
+
+# DOC501
+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.
+    """
+    raise AnotherError()
+
+
+# DOC501
+def foo(bar: int):
+    """Foo.
+
+    Args:
+        bar: Bar.
+    """
+    raise something.SomeError
+
+
+# DOC501, but can't resolve the error
+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.
+    """
+    raise _some_error
+
+
+# OK
+def calculate_speed(distance: float, time: float) -> float:
+    try:
+        return distance / time
+    except ZeroDivisionError as exc:
+        raise FasterThanLightError from exc
+
+
+# OK
+def calculate_speed(distance: float, time: float) -> float:
+    raise NotImplementedError
+
+
+# OK
+def foo(bar: int):
+    """Foo.
+
+    Args:
+        bar: Bar.
+
+    Raises:
+        SomeError: Wow.
+    """
+    raise something.SomeError
+
+
+# OK
+def foo(bar: int):
+    """Foo.
+
+    Args:
+        bar: Bar.
+
+    Raises:
+        something.SomeError: Wow.
+    """
+    raise something.SomeError

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC501_numpy.py

@@ -0,0 +1,78 @@
+class FasterThanLightError(Exception):
+    ...
+
+
+# OK
+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
+
+
+# DOC501
+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.
+    """
+    try:
+        return distance / time
+    except ZeroDivisionError as exc:
+        raise FasterThanLightError from exc
+
+
+# DOC501
+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.
+    """
+    try:
+        return distance / time
+    except ZeroDivisionError as exc:
+        raise FasterThanLightError from exc
+    except:
+        raise ValueError

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC502_google.py

@@ -0,0 +1,58 @@
+class FasterThanLightError(Exception):
+    ...
+
+
+# DOC502
+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.
+    """
+    return distance / time
+
+
+# DOC502
+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.
+        DivisionByZero: Divide by zero.
+    """
+    return distance / time
+
+
+# DOC502
+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.
+        DivisionByZero: Divide by zero.
+    """
+    try:
+        return distance / time
+    except ZeroDivisionError as exc:
+        raise FasterThanLightError from exc