1 files changed, 31 insertions, 4 deletions
diff --git a/documentation.py b/documentation.py
index 192ebfb..96b3d45 100644
--- a/documentation.py
+++ b/documentation.py
@@ -428,12 +428,12 @@ Each call to ``write`` will create a new writer thread, but there will
 be no synchronization problems since ``write`` is locked.
 
 >>> write("data1") # doctest: +ELLIPSIS
-<Thread(write-1, started ...)>
+<Thread(write-1, started...)>
 
 >>> time.sleep(.1) # wait a bit, so we are sure data2 is written after data1
 
 >>> write("data2") # doctest: +ELLIPSIS
-<Thread(write-2, started ...)>
+<Thread(write-2, started...)>
 
 >>> time.sleep(2) # wait for the writers to complete
 
@@ -466,6 +466,9 @@ were the function is generated by ``exec``. Here is an example:
  >>> f1(1,2)
  (1, 2) {}
 
+It is important to notice that the function body is interpolated
+before being executed, so be careful with the ``%`` sign!
+
 ``FunctionMaker.create`` also accepts keyword arguments and such
 arguments are attached to the resulting function. This is useful
 if you want to set some function attributes, for instance the
@@ -474,7 +477,7 @@ docstring ``__doc__``.
 For debugging/introspection purposes it may be useful to see
 the source code of the generated function; to do that, just
 pass the flag ``addsource=True`` and a ``__source__`` attribute will
-be added to the decorated function:
+be added to the generated function:
 
 .. code-block:: python
 
@@ -485,6 +488,24 @@ be added to the decorated function:
      f(a, b)
  <BLANKLINE>
 
+``FunctionMaker.create`` can take as first argument a string,
+as in the examples before, or a function. This is the most common
+usage, since typically you want to decorate a pre-existing
+function. A framework author may want to use directly ``FunctionMaker.create``
+instead of ``decorator``, since it gives you direct access to the body
+of the generated function. For instance, suppose you want to instrument
+the ``__init__`` methods of a set of classes, by preserving their
+signature (such use case is not made up; this is done in SQAlchemy
+and in other frameworks). When the first argument of ``FunctionMaker.create``
+is a function, a ``FunctionMaker`` object is instantiated internally,
+with attributes ``args``, ``varargs``,
+``keywords`` and ``defaults`` which are the
+the return values of the standard library function ``inspect.getargspec``.
+For each argument in the ``args`` (which is a list of strings containing
+the names of the mandatory arguments) an attribute ``arg0``, ``arg1``,
+..., ``argN`` is also generated. Finally, there is a ``signature`` 
+attribute, a string with the signature of the original function.
+
 Notice that while I do not have plans
 to change or remove the functionality provided in the
 ``FunctionMaker`` class, I do not guarantee that it will stay
@@ -1060,9 +1081,15 @@ def fact(n): # this is not tail-recursive
 def atest_for_pylons():
     """
     In version 3.1.0 decorator(caller) returned a nameless partial
-    object, thus breaking Pylons. That must not happen anymore.
+    object, thus breaking Pylons. That must not happen again.
+
     >>> decorator(_memoize).__name__
     '_memoize'
+
+    Here is another bug of version 3.1.1 to avoid:
+
+    >>> deprecated.__doc__
+    'A decorator for deprecated functions'
     """
 
 if __name__ == '__main__':