[Numpy-discussion] Improving Docs on Wiki

Gary Strangman strang@nmr.mgh.harvard....
Fri Mar 21 06:53:21 CDT 2008


> 4. Update the docstring, using the format suggested in
>
>   http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines

I realize this is a bit of a johnny-come-lately comment, but I was 
surprised to see that the list of sections does not seem to include the 
single most common reason I usually try to access a doc string ... the 
function signature. IMO, this item would ideally be the last item in a 
docstring so that one could quickly figure out which parameter belongs in 
which position, which are keywords, and what the defaults are without 
scrolling up multiple pages or having to mentally assemble this from a 
vertical list of parameters and optional parameters.

Was this omission deliberate or an oversight? And more importantly, what 
do people think of adding it to the guidelines?

Gary


More information about the Numpy-discussion mailing list