remove EIGEN_REF_TO_TEMPORARY, clarify docs

1 files changed, 6 insertions, 6 deletions

diff --git a/doc/I13_FunctionsTakingEigenTypes.dox b/doc/I13_FunctionsTakingEigenTypes.dox
index e67430feb..ef71e6f19 100644
--- a/doc/I13_FunctionsTakingEigenTypes.dox
+++ b/doc/I13_FunctionsTakingEigenTypes.dox
@@ -110,7 +110,7 @@ the compiler will fail, because it is not possible to convert the expression ret
 The solution which is preferred at the moment is based on a little \em hack. One needs to pass a const reference to the matrix and internally the constness needs to be cast away. The correct implementation for C98 compliant compilers would be
 \code
 template <typename Derived, typename OtherDerived>
-void cov(const MatrixBase<Derived>& x, const MatrixBase<Derived>& y, MatrixBase<OtherDerived> EIGEN_REF_TO_TEMPORARY C)
+void cov(const MatrixBase<Derived>& x, const MatrixBase<Derived>& y, MatrixBase<OtherDerived> const & C)
 {
   typedef typename Derived::Scalar Scalar;
   typedef typename internal::plain_row_type<Derived>::type RowVectorType;
@@ -140,7 +140,7 @@ cov(x, y, C);
 This is not the case anymore, when we are using an implementation taking MatrixBase as a parameter. In general, Eigen supports automatic resizing but it is not possible to do so on expressions. Why should resizing of a matrix Block be allowed? It is a reference to a sub-matrix and we definitely don't want to resize that. So how can we incorporate resizing if we cannot resize on MatrixBase? The solution is to resize the derived object as in this implementation.
 \code
 template <typename Derived, typename OtherDerived>
-void cov(const MatrixBase<Derived>& x, const MatrixBase<Derived>& y, MatrixBase<OtherDerived> EIGEN_REF_TO_TEMPORARY C_)
+void cov(const MatrixBase<Derived>& x, const MatrixBase<Derived>& y, MatrixBase<OtherDerived> const & C_)
 {
   typedef typename Derived::Scalar Scalar;
   typedef typename internal::plain_row_type<Derived>::type RowVectorType;
@@ -156,16 +156,16 @@ void cov(const MatrixBase<Derived>& x, const MatrixBase<Derived>& y, MatrixBase<
   C = (x.rowwise() - x_mean).transpose() * (y.rowwise() - y_mean) / num_observations;
 }
 \endcode
-This implementation is now working for paramters being expressions and for parameters being matrices and having the wrong size. Resizing the expressions does not do any harm in this case unless they actually require resizing. That means, passing an expression with the wrong dimensions will result in a run-time error (in debug mode only) while passing expressions of the correct size will just work fine.
+This implementation is now working for parameters being expressions and for parameters being matrices and having the wrong size. Resizing the expressions does not do any harm in this case unless they actually require resizing. That means, passing an expression with the wrong dimensions will result in a run-time error (in debug mode only) while passing expressions of the correct size will just work fine.
 
 \b Note: In the above discussion the terms Matrix and Array and MatrixBase and ArrayBase can be exchanged and all arguments still hold.
 
 \section TopicSummary Summary
 
-  - To summarize, the implementation of functions taking non-writable (const referenced) objects is not a big issue and does not lead to problematic situations in terms of compiling and running your program. However, such an implementation is likely to introduce unnecessary temporary objects in your code. In case you care about optimal run-time performance, use (const) references to MatrixBase or ArrayBase, i.e. write templated functions.
+  - To summarize, the implementation of functions taking non-writable (const referenced) objects is not a big issue and does not lead to problematic situations in terms of compiling and running your program. However, a naive implementation is likely to introduce unnecessary temporary objects in your code. In order to avoid evaluating parameters into temporaries, pass them as (const) references to MatrixBase or ArrayBase (so templatize your function).
 
-  - Writing portable functions taking parameters that are writable (non-const) requires to implement the functions such that they take const references to MatrixBase or ArrayBase. To be precise, writable objects require to use Eigen's macro EIGEN_REF_TO_TEMPORARY and casting away constness within the function. On modern compilers supporting the C++0x standard, such functions can be implemented based on r-value references though this solution is not backwards compatible with older compiler versions.
+  - Functions taking writable (non-const) parameters must take const references and cast away constness within the function body.
 
-  - Regarding resizing objects, in particular in functions that take as parameters MatrixBase (or ArrayBase), the actual resizing has to be performed on the derived class.
+  - Functions that take as parameters MatrixBase (or ArrayBase) objects, and potentially need to resize them (in the case where they are resizable), must call resize() on the derived class, as returned by derived().
 */
 }