def fix_doc(func, decorator):
    """Fix a decorated function with docs about its decorator

    :param func:        Decorated function.

    :param decorator:   The decorator that decorated func.

    ~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-~-

    PURPOSE:   Modify func.__doc__ to describe the decorator.
               You can use the `fix_doc` function to make sure your
               decorator fixes docs of a decorated function when writing
               your own decorators as illustrated below.

   SEE ALSO:   See also the `withdoc` which can apply this to existing
               decorators.

>>> import functools
>>> def withfun(func):  # Write a decorator to illustrate how to use fix_doc
...     "Print how fun a function was after calling it."
...     @functools.wraps(func)
...     def decorated(*args, **kwargs):
...         "Function with fun"
...         result = func(*args, **kwargs)
...         name = getattr(func, '__name__', '(unknown)')
...         print('Calling %s was fun!' % name)
...         return result
...     fix_doc(decorated, withfun)
...     return decorated
...
>>> @withfun
... def add(x, y):
...     "Add x and y together."
...     return x + y
...
>>> print(add.__doc__)
Add x and y together.
-------
Wrapped by decorator withfun:
Print how fun a function was after calling it.

    """
    if not func.__doc__:
        func.__doc__ = 'Function %s' % func.__name__
    extra = '\n-------\nWrapped by decorator %s' % getattr(
        decorator, '__name__', '(unknown)')
    if decorator.__doc__:
        extra += ':\n%s' % decorator.__doc__
    func.__wrapdoc__ = extra
    func.__doc__ += extra
    return func