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)?
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.