[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
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.
Thx,
Skip
More information about the Doc-SIG
mailing list