[Numpy-discussion] Improving Docs on Wiki
Stéfan van der Walt
Fri Mar 21 10:27:52 CDT 2008
On Fri, Mar 21, 2008 at 12:53 PM, Gary Strangman
> > 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?
No, this is not an oversight but a way to avoid duplicating the same
information. In IPython, use the "?" to view the docstring, and the
first thing you'll see is the function signature. For C functions we
do include the signature, since it isn't shown.
More information about the Numpy-discussion