How to document properties parameters?

[sdiebolt]

I'm wondering how to porperly document property getters and setters. Until now, I've been documenting everything in the getter, leaving the setter without docstring. That way, the generated HTML documentation shows the whole property documentation. However, I get a PR02: Unknown parameters warning on my getters since they have a Parameters section documenting the parameters of the setter. What am I doing wrong?

[timhoffm]

Why do you need a parameters section on properties at all? Properties are logically attributes, i.e. repesent one value that can be read or written. Docstrings are meant for the user and for them, properties appear attribute-like. The functions and their parameters are an implementation detail that's not relevant for the documentation.

I would suggest to document it like this:

class Rectangle:
    ...

    @property
    def width(self) -> float:
        """The width of the rectangle."""
        return self._width

    @width.setter
    def width(self, w: float) -> None:
        self._width = w

This is analogous to the attribute definition

class Rectangle:

    width : float
    """The width of the rectangle."""