feature: Support D417 for __init__ Parameters in numpy class docstrings

[tlambert03]

(I think this could technically be called a bug rather than a feature request, but ruff's current behavior is consistent with pydocstyle's, so let's call it a feature request :smile:)

issue: if __init__ parameters are documented in the class docstring, they are not caught by D417

In the class docstrings section of the numpy docstring style guide, they state that __init__ parameters should actually be documented in the class docstrings:

Class docstring

Use the same sections as outlined above (all except Returns > are applicable). The constructor (__init__) should also be documented here, the Parameters section of the docstring details the constructor’s parameters.

Obviously, this one is trickier: there's a fair degree of variation out there in source code, with many still using the __init__ docstring to document the constructor parameters. The sphinx docstring parser napoleon also supports putting the parameters in either docstring, see ExampleClass here, where they say:

    The __init__ method may be documented in either the class level
    docstring, or as a docstring on the __init__ method itself.

    Either form is acceptable, but the two should not be mixed. Choose one
    convention to document the __init__ method and be consistent with it.

Anyway, not sure how you'd like to handle this one, but thought I'd bring it to your attention.

thanks again!

---

edit: here's an example of a class that I would like to throw a D417 error for a missing b argument:

class C:
    """Summary.

    Parameters
    ----------
    a : int
        Description.
    """

    # b is not documented above
    def __init__(self, a: int, b: str) -> None:
        ...

[charliermarsh]

Heh, I think it’s fair to call this a bug. Should fix. A little more complex of course since it requires some bookkeeping…

[tlambert03]

what's your gut feeling? support both __init__ and class docstrings like napoleon? or just look in class docstrings like the spec says?

[charliermarsh]

My gut is to support either, like napoleon. (Maybe biased since I tend to document the init.)

[my1e5]

Adding to this, it would be nice to pick up missing attributes in dataclasses/attrs.

For example

@dataclass
class Foo:
    """My class.

    Attributes:
        x: The x attribute.
    """

    x: int
    y: float
    _z: bool

And perhaps if the attribute is prefixed with an _ then it is optional whether that gets included in the docstring? But I'm not sure if that's a widely accepted practice.