[EMAIL PROTECTED] 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 - [EMAIL PROTECTED] http://mail.python.org/mailman/listinfo/doc-sig
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
