[Numpy-discussion] Docstring standards for NumPy and SciPy

[Travis Oliphant]

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.
>
>  
>
>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.
>  
>

Both of these are normally not given because they are available from 
introspection, and most help facilities will print them out before the 
actual docstring.

-Travis