Some of the confusion encountered when writing decorators arise from the difference between a decorator (@something) and a decorator factory (@something(args)).  It would help to adopt this clearer terminology in our docs: a decorator takes the decorated function as argument and does its business, a decorator factory takes some arguments and returns a decorator which wraps the decorated function.

(I think it was Nick who suggested this in a recent-ish mailing list thread.)