[Doc-SIG] Double specification of function signatures?

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 Doc-SIG mailing list