title: Signature-changing decorator: properly documenting additional argument
body: <p>Let's say I have a custom decorator, and I want it to properly handle docstring of decorated function. Problem is: my decorator adds an argument. </p>
  
  <pre><code>from functools import wraps
  
  def custom_decorator(f):
      @wraps(f)
      def wrapper(arg, need_to_do_more):
          '''
          :param need_to_do_more: if True: do more
          '''
          args = do_something(arg)
  
          if need_to_do_more:
              args = do_more(args)
  
          return f(args)
  
      return wrapper
  </code></pre>
  
  <p>You can see the argument is not actually passed to decorated function, but used by the wrapper - which may or may
  not be relevant here.</p>
  
  <p>How can I properly handle documenting the additional argument?
  Is it a good practice for a wrapper to take an additional argument, or should I avoid it? </p>
  
  <p>Or should I rather use a different solution, like:</p>
  
  <ul>
  <li>making wrapper a simple higher order function, with the function it calls passed as the third argument</li>
  <li>refactoring the wrapper into two separate functions?</li>
  </ul>