Fix the documentation for CostFunction::Evaluate.

The documentation was overly complex and had mismatched
symbols leading to confusion.

Change-Id: I25709e61ff3f9b9775d8f14a9e63f61931256dac

docs/source/nnls_modeling.rst

diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index 36ee550..88df6b8 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -61,14 +61,16 @@
 =====================
 
 For each term in the objective function, a :class:`CostFunction` is
-responsible for computing a vector of residuals and if asked a vector
-of Jacobian matrices, i.e., given :math:`\left[x_{i_1}, ... ,
-x_{i_k}\right]`, compute the vector
-:math:`f_i\left(x_{i_1},...,x_{i_k}\right)` and the matrices
+responsible for computing a vector of residuals and Jacobian
+matrices. Concretely, consider a function
+:math:`f\left(x_{1},...,x_{k}\right)` that depends on parameter blocks
+:math:`\left[x_{1}, ... , x_{k}\right]`.
 
- .. math:: J_{ij} = \frac{\partial}{\partial
-           x_{i_j}}f_i\left(x_{i_1},...,x_{i_k}\right),\quad \forall j
-           \in \{1, \ldots, k\}
+Then, given :math:`\left[x_{1}, ... , x_{k}\right]`,
+:class:`CostFunction` is responsible for computing the vector
+:math:`f\left(x_{1},...,x_{k}\right)` and the Jacobian matrices
+
+.. math:: J_i =  \frac{\partial}{\partial x_i} f(x_1, ..., x_k) \quad \forall i \in \{1, \ldots, k\}
 
 .. class:: CostFunction
 
@@ -100,37 +102,43 @@
 
    Compute the residual vector and the Jacobian matrices.
 
-   ``parameters`` is an array of pointers to arrays containing the
-   various parameter blocks. ``parameters`` has the same number of
-   elements as :member:`CostFunction::parameter_block_sizes_` and the
-   parameter blocks are in the same order as
-   :member:`CostFunction::parameter_block_sizes_`.
+   ``parameters`` is an array of arrays of size
+   :member:`CostFunction::parameter_block_sizes_.size()` and
+   ``parameters[i]`` is an array of size
+   ``parameter_block_sizes_[i]`` that contains the
+   :math:`i^{\text{th}}` parameter block that the ``CostFunction``
+   depends on.
+
+   ``parameters`` is never ``NULL``.
 
    ``residuals`` is an array of size ``num_residuals_``.
 
-   ``jacobians`` is an array of size
-   :member:`CostFunction::parameter_block_sizes_` containing pointers
-   to storage for Jacobian matrices corresponding to each parameter
-   block. The Jacobian matrices are in the same order as
-   :member:`CostFunction::parameter_block_sizes_`. ``jacobians[i]`` is
-   an array that contains :member:`CostFunction::num_residuals_` x
-   :member:`CostFunction::parameter_block_sizes_` ``[i]``
-   elements. Each Jacobian matrix is stored in row-major order, i.e.,
-   ``jacobians[i][r * parameter_block_size_[i] + c]`` =
-   :math:`\frac{\partial residual[r]}{\partial parameters[i][c]}`
+   ``residuals`` is never ``NULL``.
 
+   ``jacobians`` is an array of arrays of size
+   :member:`CostFunction::parameter_block_sizes_.size()`.
 
-   If ``jacobians`` is ``NULL``, then no derivatives are returned;
-   this is the case when computing cost only. If ``jacobians[i]`` is
-   ``NULL``, then the Jacobian matrix corresponding to the
-   :math:`i^{\textrm{th}}` parameter block must not be returned, this
-   is the case when a parameter block is marked constant.
+   If ``jacobians`` is ``NULL``, the user is only expected to compute
+   the residuals.
 
-   **NOTE** The return value indicates whether the computation of the
-   residuals and/or jacobians was successful or not.
+   ``jacobians[i]`` is a row-major array of size ``num_residuals x
+   parameter_block_sizes_[i]``.
 
-   This can be used to communicate numerical failures in Jacobian
-   computations for instance.
+   If ``jacobians[i]`` is **not** ``NULL``, the user is required to
+   compute the Jacobian of the residual vector with respect to
+   ``parameters[i]`` and store it in this array, i.e.
+
+   ``jacobians[i][r * parameter_block_sizes_[i] + c]`` =
+   :math:`\frac{\displaystyle \partial \text{residual}[r]}{\displaystyle \partial \text{parameters}[i][c]}`
+
+   If ``jacobians[i]`` is ``NULL``, then this computation can be
+   skipped. This is the case when the corresponding parameter block is
+   marked constant.
+
+   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.
 
 :class:`SizedCostFunction`
 ==========================