I am trying to document a Python callable class by using docstring so that I can auto-generate documentation in Sphinx.
I am using the autoDocstring plugin for generating docstring stubs.
For classes featuring __call__ method it seems to format the class description as if it was a function. -It adds :return: field in Sphinx docstring.
This makes sense, as then -- when writing code that uses an object of this class -- Visual Studio Code shows description of the class rather than its __call__ method:
That's fine, but it requires me to document the class as if it was a function.
Of course the intention of objects of callable classes is to behave as functions, but I have the feeling it's not correct for class docstring to have :return:.
The :return: field obviously shall be in __call__ method's docstring, as otherwise it may confuse less experienced Python programmers and in such case it is not a clear documentation.
Questions:
- Shall I just write the class docstring for callable as if it was a function, keeping the format suggested by autoDocstring plugin?
- Is this an accepted standard for documenting classes with
__call__method in Python?
Below you will find a sample class used to generate the screenshot above.
class MultiplyBy:
"""Functor class for multiplying a number by fixed value
:return: Multiplied value
:rtype: float
"""
def __init__(self, multiplier: float) -> None:
"""Creates multiplier objects
Multiplier objects may be used to multipliy arbitratry number
by a fixed multiplier.
:param multiplier: Fixed multiplier value to be used for multiplying other numbers
:type multiplier: float
"""
self.multiplier = multiplier
def __call__(self, value: float) -> float:
"""Multiplies a number by a fixed value
Returns a number being the value provided multiplied
by a fixed value specified at the multiplier object construction time.
:param value: The value to be multiplied
:type value: float
:return: The value multiplied by the fixed multiplier
:rtype: float
"""
return value * self.multiplier
And the code of sample.py
from multiplier import MultiplyBy
double = MultiplyBy(2.0)
doubled = double(5.0)
