[SciPy-user] Docstring standards for NumPy and SciPy

Fernando Perez fperez.net at gmail.com
Wed Jan 17 16:48:36 CST 2007


On 1/17/07, Gary Ruben <gruben at bigpond.net.au> wrote:
> I think the :Returns: section is missing.
>
> Is see-also to be included at the end of the Notes section. For
> see-also, Ed says we can just add ":see: `frobble`" markup, so we should
> be able to just add a line like in the numpy example list on the wiki.
>
> I'm not clear on what the :Keywords: section adds. I think the 2nd
> example is just as good.

No, please let's explicitly differentiate between keywords and
positional arguments.  I don't care much what they are called, but
there's a sharp functional difference in the language between the two:
you can NOT omit positional arguments while you can omit keywords (or
call them arguments-with-defaults, or whatever).

So a big -100 from me on conflating two things which are very very
distinct at the language level (and yes, I know you can reorder a call
in python if you use named arguments for everything, etc.  My point
still stands).

Cheers,

f


More information about the SciPy-user mailing list