Double specification of function signatures?
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
skip@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@python.org http://mail.python.org/mailman/listinfo/doc-sig
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
On Sun, Apr 27, 2008 at 3:29 PM, skip@pobox.com wrote:
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.
They shouldn't. Maybe the tempfile module came from a third-party that had some internal doc rule of mentioning the call signature. Regardless, just rip it out.
-Brett
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
skip@pobox.com writes:
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),
+1 on GSoC, except for the bad timing (maybe somebody will start sponsoring a "Winter Coding Sprint" event?)
On Sun, Apr 27, 2008 at 4:40 PM, Stephen J. Turnbull stephen@xemacs.org wrote:
skip@pobox.com writes:
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),
+1 on GSoC, except for the bad timing (maybe somebody will start sponsoring a "Winter Coding Sprint" event?)
It can still go on the wiki, though, so we don't forget about it.
-Brett
>> > 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),
Brett> It can still go on the wiki, though, so we don't forget about it.
Done.
Skip
participants (4)
-
Brett Cannon -
Michael Foord -
skip＠pobox.com -
Stephen J. Turnbull