[Numpy-discussion] Improving Docs on Wiki

[Stéfan van der Walt]

Hi Gary

On Fri, Mar 21, 2008 at 12:53 PM, Gary Strangman
<strang at nmr.mgh.harvard.edu> wrote:
>
>  > 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.

Regards
Stéfan