Python decorator (factory function) to add a frequently-used docstring to a function. Existing docstrings are not overwritten.

add_docstring_decorator.py

def add_docstring(*args):  # decorator factory function
   """
   Constructs and appends a docstring to the decorated function's existing docstring.
   
   When several functions share the same docstring(s), can be used to improve code readability.
   Also makes life easier should the documentation ever need to be updated.
   
   To understand decorators: simeonfranklin.com/blog/2012/jul/1/python-decorators-in-12-steps/
   'join' a list of strings ('+' building is quadratic time): memonic.com/user/pneff/folder/python/id/1bufp
   """
   from os import linesep
   appended_docstring = [] # docstring_decorator can access variables local to its enclosing scope
                           # even when executed outside of that scope (http://tinyurl.com/anacc9n)
   if 'return_double' in args:
      appended_docstring.append('@return: (x, y)')
   elif 'return_triple' in args:
      appended_docstring.append('@return: (x, y, z)')
   if 'raise_TypeError' in args:
      appended_docstring.extend([linesep, '@raise TypeError: DFT_dim must be an integer'])
   appended_docstring = appended_docstring.strip()

   def docstring_decorator(func): # actual decorator; its only argument is the decorated function
      existing_docstring = [func.__doc__.strip(), linesep, linesep] if func.__doc__ else []
      func.__doc__ = ' '.join(existing_docstring.extend(appended_docstring))
      return func

   return docstring_decorator     # @add_docstring(*args) evaluates to the appropriate @docstring_decorator
   

@add_docstring('return_double')
def update_coords(*args, **kwargs):
  # do stuff
  return (x, y)