Fix the docs for Problem::RemoveResidualBlock & Problem::RemoveParameterBlock
The documentation was out of date about how memory management is
done in Problem.
https://github.com/ceres-solver/ceres-solver/issues/699
Change-Id: Ie55027796bc372cdcbaaca2bf2c93643c303a8e5
diff --git a/docs/source/gradient_tutorial.rst b/docs/source/gradient_tutorial.rst
index aea407a..1264847 100644
--- a/docs/source/gradient_tutorial.rst
+++ b/docs/source/gradient_tutorial.rst
@@ -165,8 +165,8 @@
And finally, if you would rather compute the derivatives by hand (say
because the size of the parameter vector is too large to be
automatically differentiated). Then you should define an instance of
-``FirstOrderFunction``, which is the analog of :class:`CostFunction`
-for non-linear least squares problems [#f3]_.
+`FirstOrderFunction`, which is the analog of :class:`CostFunction` for
+non-linear least squares problems [#f3]_.
.. code::
diff --git a/docs/source/nnls_modeling.rst b/docs/source/nnls_modeling.rst
index c0c3227..9f62aa6 100644
--- a/docs/source/nnls_modeling.rst
+++ b/docs/source/nnls_modeling.rst
@@ -1798,13 +1798,20 @@
.. function:: void Problem::RemoveResidualBlock(ResidualBlockId residual_block)
- Remove a residual block from the problem. Any parameters that the residual
- block depends on are not removed. The cost and loss functions for the
- residual block will not get deleted immediately; won't happen until the
- problem itself is deleted. If Problem::Options::enable_fast_removal is
- true, then the removal is fast (almost constant time). Otherwise, removing a
- residual block will incur a scan of the entire Problem object to verify that
- the residual_block represents a valid residual in the problem.
+ Remove a residual block from the problem.
+
+ Since residual blocks are allowed to share cost function and loss
+ function objects, Ceres Solver uses a reference counting
+ mechanism. So when a residual block is deleted, the reference count
+ for the corresponding cost function and loss function objects are
+ decreased and when this count reaches zero, they are deleted.
+
+ If Problem::Options::enable_fast_removal is true, then the removal
+ is fast (almost constant time). Otherwise it is linear, requiring a
+ scan of the entire problem.
+
+ Removing a residual block has no effect on the parameter blocks
+ that the problem depends on.
**WARNING:** Removing a residual or parameter block will destroy
the implicit ordering, rendering the jacobian or residuals returned
@@ -1814,14 +1821,16 @@
.. function:: void Problem::RemoveParameterBlock(const double* values)
- Remove a parameter block from the problem. The parameterization of
- the parameter block, if it exists, will persist until the deletion
- of the problem (similar to cost/loss functions in residual block
- removal). Any residual blocks that depend on the parameter are also
- removed, as described above in RemoveResidualBlock(). If
- Problem::Options::enable_fast_removal is true, then
- the removal is fast (almost constant time). Otherwise, removing a
- parameter block will incur a scan of the entire Problem object.
+ Remove a parameter block from the problem. Any residual blocks that
+ depend on the parameter are also removed, as described above in
+ RemoveResidualBlock().
+
+ The parameterization of the parameter block, if it exists, will
+ persist until the deletion of the problem.
+
+ If Problem::Options::enable_fast_removal is true, then the removal
+ is fast (almost constant time). Otherwise, removing a parameter
+ block will scan the entire Problem.
**WARNING:** Removing a residual or parameter block will destroy
the implicit ordering, rendering the jacobian or residuals returned
@@ -1944,8 +1953,7 @@
If `Problem::Options::enable_fast_removal` is
`true`, then getting the residual blocks is fast and depends only
on the number of residual blocks. Otherwise, getting the residual
- blocks for a parameter block will incur a scan of the entire
- :class:`Problem` object.
+ blocks for a parameter block will scan the entire problem.
.. function:: const CostFunction* Problem::GetCostFunctionForResidualBlock(const ResidualBlockId residual_block) const
