David Andreoletti David Andreoletti - 2 months ago 8
Python Question

How to document a method with parameter(s)?

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

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


Environement: Python 2.7.1

Answer

Based on my experience, the numpy docstring conventions (PEP257 superset) are the most widely-spread followed conventions that are also supported by tools, such as Sphinx.

One example:

Parameters
----------
x : type
   Description of parameter `x`.
Comments