Documenting functions in a standard way #41

We should really document our function using some sort of standard (can be our own), where input and output are clear.
Any suggestions on a standard?

def myfunc(x, y=2.0):
    """My function that does this and that.

    Input
    -----
    x : int
      The first variable.
    y : float
      The second variable (default: 2)

    Output
    ------
    r : list
      The result from x and y
    """

Something like that maybe? It will take some time to do, but it is extremely important for future users (and us).