David Andreoletti - 1 year ago 60

Python Question

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

...

Answer Source

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