Double specification of function signatures?

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Double specification of function signatures?

Skip Montanaro-3
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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Double specification of function signatures?

Michael Foord-5
[hidden email] 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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>  

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: Double specification of function signatures?

Skip Montanaro-3

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

That's my position as well.  Currently we have no way to extract the
function signatures from C code on-the-fly or in a preprocessing step (might
be a good GSoC project), but for functions written in Python I'm of the
opinion the docstrings should not include function signatures.

Skip
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] Double specification of function signatures?

Skip Montanaro-3

    Brett> They shouldn't. Maybe the tempfile module came from a third-party
    Brett> that had some internal doc rule of mentioning the call signature.
    Brett> Regardless, just rip it out.

Done.

Skip
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig