[SciPy-user] Docstring standards for NumPy and SciPy

[Pierre GM]

On Wednesday 10 January 2007 10:55, Alan G Isaac wrote:
> On Wed, 10 Jan 2007, Travis Oliphant apparently wrote:
> > I'm strongly against line-noise in the docstrings.
>
> Although I am a user not a developer, I have some experience
> with reStructuredText and epydoc, and I wonder if they are
> as "noisy" as you fear.

My 2c: 

I'd be happier if we'd stick to reST. As Alan mentioned, the format is simple, 
not cluttered, and the tools are already here. Why yet another format ? 
Travis, what do you consider as 'noise' in the rest fields ?

I also second Stefan's suggestion: I'm not really interested in knowing who 
wrote a particular piece of code when trying to access the docstring of a 
function. 

Now, Travis, if your example is very generic and covers also the docstring of 
a full module, that's different. But then it might be worth to add 
some :date: and :version: fields.


> """
> one-line summary not using variable names or the function name
>
> A few sentences giving an extended description.
>
> :Parameters:
>
>    `var1`
>         Explanation
>    `variable2`
>         Explanation

I like precision the type of input and the default directly in front of the 
variables:
:Parameters:
	- `var1` : ndarray
		Explanation
	- `var2` : Boolean *[False]*
		Explanation