[Numpy-discussion] Docstring standards for NumPy and SciPy
robert.kern at gmail.com
Wed Jan 10 17:53:31 CST 2007
Christian Marquardt wrote:
> Very nice!
>> one-line summary not using variable names or the function name
> I would personally prefer that the first name contains the function (but
> nor arguments) - that way, when you are scrolling back in your terminal,
> or have a version printed out, you know what function/method the
> doc string belongs to without having to refer to examples lower down.
How are you viewing the docstrings that wouldn't associate the docstring with
>> A few sentences giving an extended description.
> After the general description, but before giving the inputs and outputs,
> wouldn't it make sense to give the function signature as well? Something
> named, list, of, outputs = my_function(var1, variable2 [,kwdarg1=...])
> This would again reduce the need to have an extra look into the example
> section. Using the brackets, optional arguments and default settings
> could also be communicated easily.
Except for functions defined in C extension modules, the function signature is
introspectable. All of the good ways of viewing docstring information already
extract this data (help(), pydoc, epydoc, IPython's ? operator). Again, how are
you viewing docstrings that you don't see this information already?
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
More information about the Numpy-discussion