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

Cheers
Stéfan


More information about the SciPy-user mailing list