[Doc-SIG] Double specification of function signatures?
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
> >>> 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.
> Doc-SIG maillist - Doc-SIG at python.org
More information about the Doc-SIG