How to properly document properties with NumpyDoc

Question

I'm managing a package which uses the NumpyDoc style, and I'm trying to properly document the setters/getters of some properties.

In particular, I'm having an issue with the fact that the documentation of the setter is ignored by python, and hence all the documentation has to go into the getter. On the other hand, having both Returns and Parameters fields does not seem very intuitive. For example one could write the documentation like this

class MyVector:
    @properly
    def real(self):
        """Real part of the vector.

        Parameters
        ----------
        newreal : array-like
            New values to assign to the vector

        Returns
        -------
        real : MyVector
            Real part of the vector
        """
        pass

    @real.setter
    def real(self, newreal):
        pass

But in doing so it becomes very confusing when and how the Parameters and/or Returns apply. E.g. it is not obvious (to me at least) that Parameters apply only for the setter, and Returns applies only for the getter.

Is there a standard way of doing this that works well with NumpyDoc as well as the various doc parsers (e.g. Sphinx)?

Answer 1

The following napoleon example indicates that the "standard" way is to document the getter, setter and deleter is in the getter method, indicating that the way your are doing it is correct.