Add documentation about CostFunction::Evaluate.
Change-Id: I1df42c14f20c7c03f2a8ae21e75dda98cc592214
diff --git a/include/ceres/autodiff_cost_function.h b/include/ceres/autodiff_cost_function.h
index e758d3a..2cc3f50 100644
--- a/include/ceres/autodiff_cost_function.h
+++ b/include/ceres/autodiff_cost_function.h
@@ -40,8 +40,11 @@
// this is hidden, and you should write the function as if T were a scalar type
// (e.g. a double-precision floating point number).
//
-// The function must write the computed value in the last argument (the only
-// non-const one) and return true to indicate success.
+// The function must write the computed value in the last argument
+// (the only non-const one) and return true to indicate
+// success. Please see cost_function.h for details on how the return
+// value maybe used to impose simple constraints on the parameter
+// block.
//
// For example, consider a scalar error e = k - x'y, where both x and y are
// two-dimensional column vector parameters, the prime sign indicates
diff --git a/include/ceres/cost_function.h b/include/ceres/cost_function.h
index 9b010f7..8013e96 100644
--- a/include/ceres/cost_function.h
+++ b/include/ceres/cost_function.h
@@ -93,6 +93,24 @@
// the case when computing cost only. If jacobians[i] is NULL, then
// the jacobian block corresponding to the i'th parameter block must
// not to be returned.
+ //
+ // The return value indicates whether the computation of the
+ // residuals and/or jacobians was successful or not.
+ //
+ // This can be used to communicate numerical failures in jacobian
+ // computations for instance.
+ //
+ // A more interesting and common use is to impose constraints on the
+ // parameters. If the initial values of the parameter blocks satisfy
+ // the constraints, then returning false whenever the constraints
+ // are not satisfied will prevent the solver from moving into the
+ // infeasible region. This is not a very sophisticated mechanism for
+ // enforcing constraints, but is often good enough for things like
+ // non-negativity constraints.
+ //
+ // Note that it is important that the initial values of the
+ // parameter block must be feasible, otherwise the solver will
+ // declare a numerical problem at iteration 0.
virtual bool Evaluate(double const* const* parameters,
double* residuals,
double** jacobians) const = 0;
diff --git a/include/ceres/numeric_diff_cost_function.h b/include/ceres/numeric_diff_cost_function.h
index 4c84d4c..020d085 100644
--- a/include/ceres/numeric_diff_cost_function.h
+++ b/include/ceres/numeric_diff_cost_function.h
@@ -36,8 +36,10 @@
// To get an numerically differentiated cost function, you must define
// a class with a operator() (a functor) that computes the residuals.
//
-// The function must write the computed value in the last argument (the only
-// non-const one) and return true to indicate success.
+// The function must write the computed value in the last argument
+// (the only non-const one) and return true to indicate success.
+// Please see cost_function.h for details on how the return value
+// maybe used to impose simple constraints on the parameter block.
//
// For example, consider a scalar error e = k - x'y, where both x and y are
// two-dimensional column vector parameters, the prime sign indicates
