[SciPy-Dev] Docstrings for the optimize functions

[The Helmbolds]

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.

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 !!!"

Bob H