Is there a way to keep docstrings separate from the functions they document?

Question

I am working on a module with many small features, but whose dockstrips tend to be quite long. Dockstones make the work on the module annoying as I have to constantly scroll through the long dock to find some actual code.

Is there a way to keep docstrings separate from the functions they document? I would really like to specify docstrings at the end of the file, away from the code or, even better, in a separate file.

Answer 1

The docstring function for the function is available as a special attribute __doc__.

>>> def f(x):
...     "return the square of x"
...     return x * x
>>> f.__doc__
'return the square of x'
>>> help(f)
(help page with appropriate docstring)
>>> f.__doc__ = "Return the argument squared"
>>> help(f)
(help page with new docstring)

This demonstrates the technique, anyway. In practice, you can:

def f(x):
    return x * x

f.__doc__ = """
Return the square of the function argument.

Arguments: x - number to square

Return value: x squared

Exceptions: none

Global variables used: none

Side effects: none

Limitations: none
"""

... or whatever you want to insert into your docstrings.