title: How to document a method with parameter(s)?
body: <p><strong>How to document methods with parameters using Python's documentation strings?</strong></p>
  
  <p><strong>EDIT:</strong> 
  <a href="http://www.python.org/dev/peps/pep-0257/" rel="noreferrer">PEP 257</a> gives this example:</p>
  
  <pre><code>def complex(real=0.0, imag=0.0):
      """Form a complex number.
  
      Keyword arguments:
      real -- the real part (default 0.0)
      imag -- the imaginary part (default 0.0)
  
      """
      if imag == 0.0 and real == 0.0: return complex_zero
      ...
  </code></pre>
  
  <p>Is this the convention used by most Python developers ?</p>
  
  <pre><code>Keyword arguments:
  &lt;parameter name&gt; -- Definition (default value if any)
  </code></pre>
  
  <p>I was expecting something a little bit more formal such as </p>
  
  <pre><code>def complex(real=0.0, imag=0.0):
      """Form a complex number.
  
      @param: real The real part (default 0.0)
      @param: imag The imaginary part (default 0.0)
  
      """
      if imag == 0.0 and real == 0.0: return complex_zero
      ...
  </code></pre>
  
  <p><strong>Environment</strong>: Python 2.7.1</p>