[Numpy-discussion] Improving Docs on Wiki

[Pauli Virtanen]

pe, 2008-03-21 kello 07:53 -0400, Gary Strangman kirjoitti:
> > 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.

The function signature is automatically determined and shown for Python
functions, both by help() and IPython ? or most tools that do generate
docs from docstrings, adding it also to the docstring is extraneous.

For functions implemented in C in extension modules, help() cannot find
the signature automatically. However, the CodingStyleGuidelines does say
that in this case including the function signature to the documentation
is mandatory.

-- 
Pauli Virtanen