[pydocstyle] Treat backslash-escaped *args and **kwargs as documented (D417) (#29536)

## Summary

Closes #29535.

Sphinx-style docstrings often escape the stars as `\*args` and
`\*\*kwargs`, because a bare `*` starts emphasis in reST. D417 didn't
account for that, so it reported those parameters as undocumented even
though they were documented.

It went wrong in a different way for each style. In NumPy-style
sections, the name before the `:` was taken verbatim, so `\*\*kwargs`
never matched `**kwargs`. In Google-style sections, the regex didn't
accept a leading `\`, so the whole line was skipped.

I added a small `unescape_parameter_name` helper in `sections.rs` that
strips backslashes from the documented name, and both parsers now use
it. The Google regex also accepts up to two escaped stars now. Since a
backslash can't be part of a Python parameter name, removing all of them
should be safe. This also covers non-raw docstrings that write
`\\*\\*kwargs`.

## Test Plan

I added five cases to `D417.py`: escaped NumPy and Google docstrings
with every parameter documented, the same two styles with one parameter
actually missing, and a non-raw docstring. Without the fix, all five
`d417` tests fail and report `*args` and `**kwargs` as missing. With the
fix, the fully documented functions aren't flagged. In the missing
variants, only the parameters that really are missing get reported. The
snapshots are updated, and `cargo test -p ruff_linter -- pydocstyle` and
clippy both pass.

I used Claude (via T3 Code) to help with the implementation. I've
reviewed the change and can explain it.

Author: fixfon

crates/ruff_linter/resources/test/fixtures/pydocstyle/D417.py

@@ -241,3 +241,57 @@ def function_with_unpack_and_missing_arg_doc_should_fail(query: str, **kwargs: U
     Args:
         **kwargs: keyword arguments
     """
+
+
+# regression test for https://github.com/astral-sh/ruff/issues/29535.
+# reStructuredText requires `*` to be escaped with a backslash.
+def escaped_stars_numpy(x, *args, **kwargs):
+    r"""Do something.
+
+    Parameters
+    ----------
+    x : int
+        The value.
+    \*args : tuple
+        Variable arguments.
+    \*\*kwargs : dict
+        Keyword arguments.
+    """
+
+
+def escaped_stars_numpy_missing(x, *args, **kwargs):
+    r"""Do something.
+
+    Parameters
+    ----------
+    \*\*kwargs : dict
+        Keyword arguments.
+    """
+
+
+def escaped_stars_google(x, *args, **kwargs):
+    r"""Do something.
+
+    Args:
+        x: the value
+        \*args: variable arguments
+        \*\*kwargs: keyword arguments
+    """
+
+
+def escaped_stars_google_missing(x, *args, **kwargs):
+    r"""Do something.
+
+    Args:
+        \*\*kwargs: keyword arguments
+    """
+
+
+def escaped_stars_non_raw(x, *args, **kwargs):
+    """Do something.
+
+    Args:
+        x: the value
+        \\*args: variable arguments
+        \\*\\*kwargs: keyword arguments
+    """

crates/ruff_linter/src/rules/pydocstyle/mod.rs

@@ -198,7 +198,7 @@ mod tests {
         let diagnostics = test_path(
             Path::new("pydocstyle/D417.py"),
             &settings::LinterSettings {
-                // With explicit numpy convention, we shouldn't flag anything.
+                // With explicit numpy convention, we should only flag the NumPy-style docstrings.
                 pydocstyle: Settings {
                     convention: Some(Convention::Numpy),
                     ..Settings::default()

crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs

@@ -1967,8 +1967,15 @@ fn has_unpack_annotation(checker: &Checker, parameter: &Parameter) -> bool {
 }
 
 // See: `GOOGLE_ARGS_REGEX` in `pydocstyle/checker.py`.
-static GOOGLE_ARGS_REGEX: LazyLock<Regex> =
-    LazyLock::new(|| Regex::new(r"^\s*(\*?\*?\w+)\s*(\(.*?\))?\s*:(\r\n|\n)?\s*.+").unwrap());
+static GOOGLE_ARGS_REGEX: LazyLock<Regex> = LazyLock::new(|| {
+    Regex::new(r"^\s*((?:\\*\*){0,2}\w+)\s*(\(.*?\))?\s*:(\r\n|\n)?\s*.+").unwrap()
+});
+
+/// Removes the backslashes that escape `*` in reStructuredText, so that `\*\*kwargs` (or
+/// `\\*\\*kwargs` in a non-raw docstring) is treated as `**kwargs`.
+fn unescape_parameter_name(name: &str) -> String {
+    name.replace('\\', "")
+}
 
 fn args_section(context: &SectionContext) -> FxHashSet<String> {
     let mut following_lines = context.following_lines();
@@ -2018,7 +2025,11 @@ fn args_section(context: &SectionContext) -> FxHashSet<String> {
 
     matches
         .iter()
-        .filter_map(|captures| captures.get(1).map(|arg_name| arg_name.as_str().to_owned()))
+        .filter_map(|captures| {
+            captures
+                .get(1)
+                .map(|arg_name| unescape_parameter_name(arg_name.as_str()))
+        })
         .collect::<FxHashSet<String>>()
 }
 
@@ -2051,7 +2062,7 @@ fn parameters_section(checker: &Checker, docstring: &Docstring, context: &Sectio
                 // Notably, NumPy lets you put multiple parameters of the same type on the same
                 // line.
                 for parameter in parameters.split(',') {
-                    docstring_args.insert(parameter.trim().to_owned());
+                    docstring_args.insert(unescape_parameter_name(parameter.trim()));
                 }
             }
 

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_google.snap

@@ -111,3 +111,11 @@ D417 Missing argument description in the docstring for `function_with_unpack_and
     |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 |     """Function with Unpack kwargs but missing query arg documentation.
     |
+
+D417 Missing argument descriptions in the docstring for `escaped_stars_google_missing`: `*args`, `x`
+   --> D417.py:282:5
+    |
+282 | def escaped_stars_google_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+283 |     r"""Do something.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_google_ignore_var_parameters.snap

@@ -93,3 +93,11 @@ D417 Missing argument description in the docstring for `function_with_unpack_and
     |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 |     """Function with Unpack kwargs but missing query arg documentation.
     |
+
+D417 Missing argument description in the docstring for `escaped_stars_google_missing`: `x`
+   --> D417.py:282:5
+    |
+282 | def escaped_stars_google_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+283 |     r"""Do something.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_numpy.snap

@@ -1,4 +1,10 @@
 ---
 source: crates/ruff_linter/src/rules/pydocstyle/mod.rs
 ---
-
+D417 Missing argument descriptions in the docstring for `escaped_stars_numpy_missing`: `*args`, `x`
+   --> D417.py:262:5
+    |
+262 | def escaped_stars_numpy_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+263 |     r"""Do something.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_unspecified.snap

@@ -111,3 +111,19 @@ D417 Missing argument description in the docstring for `function_with_unpack_and
     |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 |     """Function with Unpack kwargs but missing query arg documentation.
     |
+
+D417 Missing argument descriptions in the docstring for `escaped_stars_numpy_missing`: `*args`, `x`
+   --> D417.py:262:5
+    |
+262 | def escaped_stars_numpy_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+263 |     r"""Do something.
+    |
+
+D417 Missing argument descriptions in the docstring for `escaped_stars_google_missing`: `*args`, `x`
+   --> D417.py:282:5
+    |
+282 | def escaped_stars_google_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+283 |     r"""Do something.
+    |

crates/ruff_linter/src/rules/pydocstyle/snapshots/ruff_linter__rules__pydocstyle__tests__d417_unspecified_ignore_var_parameters.snap

@@ -111,3 +111,19 @@ D417 Missing argument description in the docstring for `function_with_unpack_and
     |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 239 |     """Function with Unpack kwargs but missing query arg documentation.
     |
+
+D417 Missing argument descriptions in the docstring for `escaped_stars_numpy_missing`: `*args`, `x`
+   --> D417.py:262:5
+    |
+262 | def escaped_stars_numpy_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+263 |     r"""Do something.
+    |
+
+D417 Missing argument descriptions in the docstring for `escaped_stars_google_missing`: `*args`, `x`
+   --> D417.py:282:5
+    |
+282 | def escaped_stars_google_missing(x, *args, **kwargs):
+    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+283 |     r"""Do something.
+    |