[SciPy-user] Docstring standards for NumPy and SciPy
pgmdevlist at gmail.com
Wed Jan 10 10:15:39 CST 2007
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.
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
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.
I like precision the type of input and the default directly in front of the
- `var1` : ndarray
- `var2` : Boolean *[False]*
More information about the SciPy-user