[SciPy-dev] Latex and docstrings

Joe Harrington jh@physics.ucf....
Wed Feb 17 13:22:14 CST 2010


On Wed, 17 Feb 2010 09:16:50 -0700, Charles R Harris wrote:
> I don't think the docstrings should be tutorials, rather, they should state
> what the function does in simple terms. A place for more extended
> explanation might be desirable at some point for teaching purposes but I
> don't think it belongs in the docstrings.

This is rather irrelevant to the discussion at hand.  ASCII or LaTeX
formulae belong in any docstring implementing something best described
by one, particularly if there are differences in how the concept is
implemented in different numerical packages.  For example, in an FFT,
is the normalization part of the forward transform, the inverse, or
both?  A formula defines exactly what is implemented in the code,
and is usually the tersest way of presenting that (which I think is
what you're after).

If you have concerns about the general content of the docstrings, it
would be helpful if you could post them on another thread and give
some specific examples of what you are concerned about.

--jh--


More information about the SciPy-Dev mailing list