[Doc-SIG] Double specification of function signatures?

skip at pobox.com skip at pobox.com
Mon Apr 28 00:16:12 CEST 2008

While cleaning up the documentation for the tempfile module I noticed that
the docstrings for the mk*temp functions in the module itself list their
signatures (incompletely) in the first line.  I don't know if that was
intentional, but it seems both redundant and error-prone to me.  The help()
function already displays the signatures of Python functions.  There's no
need to put them in docstrings and risk having them out-of-date.  For

    >>> help(tempfile.mkdtemp)
    Help on function mkdtemp in module tempfile:

    mkdtemp(suffix='', prefix='tmp', dir=None)
        mkdtemp([suffix, [prefix, [dir]]])
        User-callable function to create and return a unique temporary
        directory.  The return value is the pathname of the directory.

Am I way off-base here?  Let me know, as I have a couple minor tweaks to
check in besides these.



More information about the Doc-SIG mailing list