[Python-Dev] [Doc-SIG] Double specification of function signatures? (original) (raw)

Michael Foord fuzzyman at voidspace.org.uk
Mon Apr 28 00:26:29 CEST 2008

skip at pobox.com wrote:

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 example:

>>> 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.

It seems that any documentation or help tool worth its salt should fetch the parameters from the definition and so including them in the docstring should be redundant duplication.

Michael Foord

Thx,

Skip

Doc-SIG maillist - Doc-SIG at python.org http://mail.python.org/mailman/listinfo/doc-sig

More information about the Python-Dev mailing list