Decorator for automatic inclusion of function definition in __doc__

Python 2.4 included support for function decorators. Decorators are callable objects that may modify a given function or class method arbitrarily when they’re prepended with specific syntax to the function/method definition.

The following code implements a decorator that will automatically include the arguments accepted by a given function in its own documentation:

import inspect
def argspec(object):
    spec = inspect.formatargspec(*inspect.getargspec(object))
    if object.__doc__:
        object.__doc__ = "%s%snn%s" % (object.__name__, spec, object.__doc__)
    else:
        object.__doc__ = "%s%s" % (object.__name__, spec)
    return object

It may be used as follows:

>>> @argspec
... def test(a,b=1,*c,**d):
...     """My test function"""
...
>>> print test.__doc__
test(a, b=1, *c, **d)

My test function

Notice that this is interesting mostly for hacking value. Most softwares that generate documentation for Python code, like the standard pydoc module, already take care of building and showing that information.