Refined the spec for some functions and also added some missing asserts.

--HG--
extra : convert_revision : svn%3Afdd8eb12-d10e-0410-9acb-85c331704f74/trunk%403192

dlib/optimization/optimization_abstract.h

@@ -117,8 +117,7 @@ namespace dlib
             - stop_strategy == an object that defines a stop strategy such as one of 
               the objects from dlib/optimization/optimization_stop_strategies_abstract.h
             - f(x) must be a valid expression that evaluates to a double
-            - der(x) must be a valid expression that evaluates to the derivative of
-              f() at x.
+            - der(x) must be a valid expression that evaluates to the derivative of f() at x.
             - is_col_vector(x) == true
         ensures
             - Performs an unconstrained minimization of the function f() using the given
@@ -152,8 +151,7 @@ namespace dlib
             - stop_strategy == an object that defines a stop strategy such as one of 
               the objects from dlib/optimization/optimization_stop_strategies_abstract.h
             - f(x) must be a valid expression that evaluates to a double
-            - der(x) must be a valid expression that evaluates to the derivative of
-              f() at x.
+            - der(x) must be a valid expression that evaluates to the derivative of f() at x.
             - is_col_vector(x) == true
         ensures
             - Performs an unconstrained maximization of the function f() using the given

dlib/optimization/optimization_line_search.h

@@ -217,7 +217,7 @@ namespace dlib
         COMPILE_TIME_ASSERT(is_function<funct_der>::value == false);
 
         DLIB_ASSERT (
-            1 > sigma && sigma > rho && rho > 0,
+            0 < rho && rho < sigma && sigma < 1,
             "\tdouble line_search()"
             << "\n\tYou have given invalid arguments to this function"
             << "\n\tsigma: " << sigma

dlib/optimization/optimization_line_search_abstract.h

@@ -136,6 +136,8 @@ namespace dlib
             - It is assumed that the minimum possible value of f(x) is min_f.  So if
               an alpha is found such that f(alpha) <= min_f then the search stops
               immediately.
+            - This function is also optimized for the case where der(0) is negative.  I.e.
+              positive values of the argument to f() should be a descent direcion.  
     !*/
 
     /*

dlib/optimization/optimization_search_strategies.h

@@ -148,7 +148,14 @@ namespace dlib
     class lbfgs_search_strategy
     {
     public:
-        lbfgs_search_strategy(unsigned long max_size_) : max_size(max_size_), been_used(false) {}
+        lbfgs_search_strategy(unsigned long max_size_) : max_size(max_size_), been_used(false) 
+        {
+            DLIB_ASSERT (
+                max_size > 0,
+                "\t lbfgs_search_strategy(max_size)"
+                << "\n\t max_size can't be zero"
+            );
+        }
 
         lbfgs_search_strategy(const lbfgs_search_strategy& item) 
         {

dlib/optimization/optimization_search_strategies_abstract.h

@@ -67,7 +67,9 @@ namespace dlib
         );
         /*!
             requires
-                - for some function f():
+                - this function is only called once per search iteration
+                - for some objective function f():
+                    - x == the search point for the current iteration
                     - funct_value == f(x)
                     - funct_derivative == derivative(f)(x)
             ensures
@@ -127,7 +129,9 @@ namespace dlib
         );
         /*!
             requires
-                - for some function f():
+                - this function is only called once per search iteration
+                - for some objective function f():
+                    - x == the search point for the current iteration
                     - funct_value == f(x)
                     - funct_derivative == derivative(f)(x)
             ensures
@@ -191,7 +195,9 @@ namespace dlib
         );
         /*!
             requires
-                - for some function f():
+                - this function is only called once per search iteration
+                - for some objective function f():
+                    - x == the search point for the current iteration
                     - funct_value == f(x)
                     - funct_derivative == derivative(f)(x)
             ensures

dlib/optimization/optimization_stop_strategies.h

@@ -19,12 +19,29 @@ namespace dlib
     public:
         objective_delta_stop_strategy (
             double min_delta = 1e-7
-        ) : _been_used(false), _min_delta(min_delta), _max_iter(0), _cur_iter(0), _prev_funct_value(0) {}
+        ) : _been_used(false), _min_delta(min_delta), _max_iter(0), _cur_iter(0), _prev_funct_value(0) 
+        {
+            DLIB_ASSERT (
+                min_delta >= 0,
+                "\t objective_delta_stop_strategy(min_delta)"
+                << "\n\t min_delta can't be negative"
+                << "\n\t min_delta: " << min_delta
+            );
+        }
 
         objective_delta_stop_strategy (
             double min_delta,
             unsigned long max_iter
-        ) : _been_used(false), _min_delta(min_delta), _max_iter(max_iter), _cur_iter(0), _prev_funct_value(0) {}
+        ) : _been_used(false), _min_delta(min_delta), _max_iter(max_iter), _cur_iter(0), _prev_funct_value(0) 
+        {
+            DLIB_ASSERT (
+                min_delta >= 0 && max_iter > 0,
+                "\t objective_delta_stop_strategy(min_delta, max_iter)"
+                << "\n\t min_delta can't be negative and max_iter can't be 0"
+                << "\n\t min_delta: " << min_delta
+                << "\n\t max_iter:  " << max_iter 
+            );
+        }
 
         template <typename T>
         bool should_continue_search (

dlib/optimization/optimization_stop_strategies_abstract.h

@@ -61,7 +61,9 @@ namespace dlib
         );
         /*!
             requires
-                - for some function f():
+                - this function is only called once per search iteration
+                - for some objective function f():
+                    - x == the search point for the current iteration
                     - funct_value == f(x)
                     - funct_derivative == derivative(f)(x)
             ensures