[SciPy-user] Docstring standards for NumPy and SciPy
Stefan van der Walt
stefan at sun.ac.za
Wed Jan 10 15:43:24 CST 2007
On Wed, Jan 10, 2007 at 02:31:29PM -0600, Robert Kern wrote:
> >> Parameters
> >> ----------
> >> var1 : type of var1 (loosely)
> >> Description of var1.
> >> variable2 : type of variable2 (loosely)
> >> Description of variable2.
> >> kwdarg : type of kwdarg, optional
> >> Description of kwdarg.
> > This is acceptable in my mind, also. Although I probably like '-'
> > instead of ':' as a separator, but just because I'm used to it.
> >> The (loose) type information is quite handy. Sometimes it is quite difficult to
> >> tell what kind of thing the function needs from the usual description,
> >> particularly when both scalars or arrays are flying around.
> > Yeah, I could see that. As you understand but others may not, we
> > shouldn't get overly specific with the "types" though. We're supposed
> > to be doing duck typing wherever possible.
> Well, there's certainly no pointless type-*checking* going on. It's just that
> when I say I want an int, for example, I'm going to be treating what you give me
> as an int whatever it happens to be, so it better quack like an int. I'm just
> explicitly stating that precondition which already existed and give users a much
> clearer idea of how they are expected to use the function. It guides the user to
> doing the sensible, expected thing without preventing them from sensible, but
> unexpected things.
I like the idea of providing a loose type. Normally, when I write
documentation, this is included in the description, i.e. "A 3xMxN
array that indicates...", but separating it from the description
actually makes a lot of sense. Duck typing is only useful when the
user knows which objects quack.
More information about the SciPy-user