how_to_write_docstring.py

import numpy as np


# a function to be finished
def cos_to_be_finished(x):
    # TODO: to be finished
    return


# a function with a simple docstring
def _cos(x):
    """ this is a cosine function """
    return np.cos(x)


# a function with a complete docstring
def cos(x: float = 0.) -> float:
    """ cosine function

    Parameters
    ----------
    x : float
        x values

    Returns
    -------
    cos(x) : float

    Examples
    --------
    >>> import numpy as np
    >>> cos(np.pi)

    Notes
    -----
    this function is a warpper of `numpy.cos()`
    """
    return np.cos(x)