Include Guido's rationale for the order of application and for the

decorator declaration syntax allowing functions with arguments.

pep-0318.txt

@@ -250,6 +250,14 @@ without the intermediate assignment to the variable ``func``.  The
 decorators are near the function declaration.  The @ sign makes it clear
 that something new is going on here.
 
+The rationale for the `order of application`_ (bottom to top) is that it
+matches the usual order for function-application.  In mathematics,
+composition of functions (g o f)(x) translates to g(f(x)).  In Python,
+``@g @f def foo()`` translates to ``foo=g(f(foo)``.
+                                          
+.. _order of application:
+    http://mail.python.org/pipermail/python-dev/2004-September/048874.html
+
 The decorator statement is limited in what it can accept -- arbitrary
 expressions will not work.  Guido preferred this because of a `gut
 feeling`_.
@@ -257,6 +265,25 @@ feeling`_.
 .. _gut feeling:
     http://mail.python.org/pipermail/python-dev/2004-August/046711.html
 
+The current syntax also allows decorator declarations to call a
+function that returns a decorator::
+
+    @decomaker(argA, argB, ...)
+    def func(arg1, arg2, ...):
+        pass
+
+This is equivalent to::
+
+    func = decomaker(argA, argB, ...)(func)
+
+The rationale for having a function that returns a decorator is that
+the part after the @ sign can be considered to be an expression
+(though syntactically restricted to just a function), and whatever
+that expression returns is called.  See `declaration arguments`_.
+
+.. _declaration arguments:
+    http://mail.python.org/pipermail/python-dev/2004-September/048874.html               
+
 
 Syntax Alternatives
 ===================