title: Amending docstrings from decoators, while retaining formattting
body: <p>I have some decorator functions which execute additional code before/after executing the function they decorate. What I'd like to do is dynamically document the additional behavior to the decorated function's docstring. I'm already retaining the name and such properties with <code>functools.wrap</code>.</p>
  
  <p>Here is a simplified example of what I'd like to do:</p>
  
  <pre><code>numbers_added = []
  
  def record_number(func):
      decorator_doc = '''\nRecord added numbers in numbers_added'''
      def add_and_record(n):
          r = func(n)
          if r is not False:
              numbers_added.append(n)
          return r
      add_and_record.__doc__ = func.__doc__ + decorator_doc
      return add_and_record
  
  @record_number
  def add2_to_even(n):
      '''Add 2 to an even number, `n`.
  
         If n is not even, return False'''
      if n % 2 == 0:
          return n + 2
      return False
  </code></pre>
  
  <p>Now, everything here works great and the docstring is successfully updated, so what's my problem? If you take a look at <code>help(add2_to_even)</code> you'll see that the second line of the docstring has not been formatted correctly. Usually any leading indentation is stripped, but in the case is is retained. What can I do to keep the formatting as would be expected?</p>
  
  <p>Note: There is an implementation of an algorithm to do this in the Python Docstring Conventions (<a href="http://legacy.python.org/dev/peps/pep-0257/#id18" rel="nofollow">PEP 257</a>), but I would rather not use something like this and re-implement core functionality.</p>