[Python-Dev] [Doc-SIG] Double specification of function signatures?

[Michael Foord]

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
>