[Numpy-discussion] Docstring standards for NumPy and SciPy

[Robert Kern]

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
the function?

>> 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
> like
> 
>   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?

-- 
Robert Kern

"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