[Python] How to document a method with parameter(s)?

How to document methods with parameters using Python's documentation strings?

PEP 257 gives this example:

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


Is this the convention used by most Python developers?

Keyword arguments:
<parameter name> -- Definition (default value if any)


I was expecting something a little bit more formal such as

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


Environment: Python 2.7.1

Continue reading...