DOC501 False Positive

[will-schneble]

Describe the bug
DOC501 rule violation when the docstring includes the exception.

ruff==0.5.5
python==3.12.4

Command: ruff check --preview --select DOC

No pyproject.toml or other configuration than what's shown here.

Steps to reproduce
Sample file to test against.

class Foo:
    def __init__(self, bar, zap):
        self.bar = bar
        self.zap = zap
        
    def get_bar(self) -> str:
        """Print and return bar.
        
        Raises:
            ValueError: bar is not bar.

        Returns:
            str: bar value.
        """    
        print(self.bar)
        if self.bar != "bar":
            raise ValueError(self.bar)
        return self.bar

Expected behavior
No violations.

Running pydoclint --style=google test.py gives the expected no violation result.

Debug logs

test.py:17:19: DOC501 Raised exception `ValueError` missing from docstring
   |
15 |         print(self.bar)
16 |         if self.bar != "bar":
17 |             raise ValueError(self.bar)
   |                   ^^^^^^^^^^^^^^^^^^^^ DOC501
18 |         return self.bar
   |

Notes
Adding an argument to Foo.get_bar and adding that to the docstring then makes the DOC501 violation go away. Example below:

    def get_bar(self, x: str) -> str:
        """Print and return bar.
        
        Args:
            x (str): A dummy value.
        
        Raises:
            ValueError: bar is not bar.

        Returns:
            str: bar value
        """    
        print(self.bar)
        if self.bar != "bar":
            raise ValueError(self.bar)
        return self.bar

[will-schneble]

Just saw ruff==0.5.6 released. Double checked and it is still an issue in that version.

[charliermarsh]

Thank you!

[charliermarsh]

I think the issue is that the above section is actually ambiguous. All the defined sections are valid section names in both NumPy and Google. You should set the convention explicitly in your pyproject.toml, e.g.:

[tool.ruff.lint.pydocstyle]
convention = "google"

(Adding Args works because Args is Google-only, so we can safely differentiate.)

[will-schneble]

You're correct, adding --config 'lint.pydocstyle.convention="google"' produces the expected results. For some reason I thought pydocstyle config didn't affect the pydoclint rules. Thanks for looking into it.

[JasonGrace2282]

It might make sense to produce a more reasonable error message instead of a vague DOC501 linting error?

[charliermarsh]

@JasonGrace2282 - can you expand on that? It’s inferring a NumPy docstring, and in that case, it can’t find any raises.

@will-schneble - gonna leave this open because I think we can improve our detection.

[JasonGrace2282]

I'm not familiar with how the parsing works in Ruff, but as a user I would expect a warning if the convention is numpy but a docstring looks like Google convention.
I understand what I just said is a bit vague (and possibly hard to implement), so really any kind of hint if the docstring convention isn't explicitly set would be useful imo.

[trim21]

this is confusing, doc use google style but it requires extra config

https://docs.astral.sh/ruff/rules/docstring-missing-exception/