[SciPy-dev] some problems with optimize.py docstrings

[dmitrey]

Hi all,
unfortunately some days ago I had a problems with internet connection 
and that's why I didn't committed updated docstrings to optimize.py. 
That time I encountered some problems and that's why I switched to other 
tasks assigned to me, and forgot to do this one in-time.

The problems that I mentioned are related to lack of documentation, and, 
moreover, to incorrect documentation.

So,

1.
def line_search(...)
"""...

Outputs: (alpha, gc, fc)
..."""
...
return alpha_star, _ls_fc, _ls_gc, fval_star, old_fval, fprime_star

1) is (gc, fc) really equal to _ls_fc, _ls_gc? Maybe vise versa?
As for me, I don't know what are those return params mean.

2) documentation has the line
"For the zoom phase it uses an algorithm by" (so what should be here?)
3) Description misses meanings of amax, old_fval, old_old_fval (same to 
line_search_BFGS)


2.
def line_search_BFGS(...)
"""...
Outputs: (alpha, fc, gc)"""
...

   if (phi_a0 <= phi0 + c1*alpha0*derphi0):
       return alpha0, fc, 0, phi_a0
#NOTE: 4 params instead of 3
...
   if (phi_a1 <= phi0 + c1*alpha1*derphi0):
       return alpha1, fc, 0, phi_a1
#same: 4 params instead of 3
...
       if (phi_a2 <= phi0 + c1*alpha2*derphi0):
           return alpha2, fc, 0, phi_a2
#same

So, as you see,
1) it has incorrect output - 4 values instead of 3
2) it doesn't describe what are those fc and gc
3) output gc is always equal to zero

On the other hand, almost noone uses the funcs except some other funcs 
from optimize.py (elseware lots of tickets would be filed). The same to 
some other funcs from optimize.py (i.e. they are used only from other 
optimize.py funcs).
So I suppose it could wait. Are you agree?


So do you want me to commit the changes I done to svn right now, before 
tomorrow scipy 0.6 release?
Let me attach to the letter links to optimize.py file as well as epydoc 
output.
Regards, D.


optimize.py
http://www.box.net/shared/3bi5n8jtln

html-file

http://www.box.net/shared/0l44js08jj