[SciPy-Dev] Docstrings for the optimize functions

[Ralf Gommers]

On Sun, Sep 30, 2012 at 8:01 PM, The Helmbolds <helmrp at yahoo.com> wrote:

> Problem: As we update the scipy.optimize docstrings, how should we deal
> with the difference between the "new style" or 'minimize' calling sequence
> and its return dictionary, and the "old style" or 'pre-minimize' calling
> sequence and return values?
>
> Background and Discussion: The docstring for the over-arching 'minimize'
> function is OK as far as it goes. However, while it mentions that the
> different methods differ in the number and/or kind of parameters in both
> their calling sequences and in their 'Results' dictionaries, it (quite
> properly) does not go into the nitty-gritty details of these items for each
> 'method'. Yet, those details should be described someplace, especially for
> new users.
>

Described in
http://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.show_options.html


>
> Suggested Approach: I propose the following approach to documenting the
> individual 'methods' while we are in this "transition" period:
>
> 1. In the Summary (or Extended Summary) of the method, include words to
> the effect that: Although this documentation for the most part describes
> the "old style" calling sequence and return values, it is strongly
> recommended that new code invoking this method use the "new style" or
> 'minimize' calling sequence and return values, and that serious
> consideration be given to updating existing code to the "new style". To
> ease the transition, one or more examples illustrating both the "old style"
> and the "new style" calling sequences and return values are provided in the
> Examples section.
>
> 2. Leave the docstring's sections on Parameters, Returns, Other
> Parameters, Raises, Notes, and References, discuss as though the "old
> style" calling sequence is being used. Add to these sections remarks on the
> "new style" only when clarity requires it. For example, it may be helpful
> to add a sentence to the Parameters and Returns sections stting that: The
> Examples section shows how to adapt this to the "new style" calling
> sequence and return values.
>
> 3. In the examples, first illustrate how to use the "old style" version.
> Then add an example illustrating how exactly the same problem would be
> handled when the "new style's" 'minimize' calling sequence is used. In that
> example discuss just so much of the details of the method's "options
> dictionary", "constraints dictionary sequence", and "Results dictionary" as
> seems necessary to guide a new user. In other words, adhere to the
> priniciple that "All documentation should be as brief as possible -- but no
> briefer !!!"
>

Many of the fmin_ docstrings have no examples. I think your suggestion of
adding first an example using that fmin_ function directly, and then below
it doing the same with minimize(method='fmin_xxx') would be useful.

The fmin_ docstrings already link to minimize() in the See Also section.
Adding a few words to that like "minimize(method='fmin_xxx') is
recommended, `fmin_` is kept for backwards compatibility" would be useful.

That's all I'd do.

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20121001/e94f18c8/attachment.html>