title: Docstring for callable class in Python
body: <p>I am trying to document a Python callable class by using docstring so that I can auto-generate documentation in Sphinx.</p>
  
  <p>I am using the <a href="https://github.com/NilsJPWerner/autoDocstring" rel="nofollow noreferrer">autoDocstring</a> plugin for generating docstring stubs.
  For classes featuring <code>__call__</code> method it seems to format the class description as if it was a function. -It adds <code>:return:</code> field in Sphinx docstring.</p>
  
  <p>This makes sense, as then -- when writing code that <strong>uses</strong> an object of this class -- Visual Studio Code shows description of the class rather than its <code>__call__</code> method:</p>
  
  <p><a href="https://i.stack.imgur.com/4SKne.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/4SKne.png" alt="enter image description here"></a></p>
  
  <p>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 <code>:return:</code>.
  The <code>:return:</code> field obviously shall be in <code>__call__</code> method's docstring, as otherwise it may confuse less experienced Python programmers and in such case it is not a clear documentation.</p>
  
  <p><strong>Questions</strong>:</p>
  
  <ul>
  <li>Shall I just write the class docstring for callable as if it was a function, keeping the format suggested by autoDocstring plugin?</li>
  <li>Is this an accepted standard for documenting classes with <code>__call__</code> method in Python?</li>
  </ul>
  
  <p>Below you will find a sample class used to generate the screenshot above.</p>
  
  <pre><code>class MultiplyBy:
  """Functor class for multiplying a number by fixed value
  
  :return: Multiplied value
  :rtype: float
  """
  
  def __init__(self, multiplier: float) -&gt; 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) -&gt; 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
  </code></pre>
  
  <p>And the code of sample.py</p>
  
  <pre><code>from multiplier import MultiplyBy
  
  double = MultiplyBy(2.0)
  
  doubled = double(5.0)
  </code></pre>