Question

For example:

def foo(length, width):
    """Short desc.

    Arguments:

    length -- A desc.
    width  -- A desc.
    """

Note how I have added an extra space after “width”.

Answer 1

I don’t think there is a convention about this. All PEP 257 says about the docstring of a function is

The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

The only example given in the PEP also doesn’t shed light on the matter:

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

I usually do align the dashes, but I don’t think there is a general convention.