From a0bcaa88af027de43306361f768c0b227d0072cb Mon Sep 17 00:00:00 2001
From: Jitse Niesen <jitse@maths.leeds.ac.uk>
Date: Thu, 1 Dec 2011 21:16:07 +0000
Subject: [PATCH] Extend tutorial page on broadcasting to reflect recent
 changes.

---
 Eigen/src/Core/VectorwiseOp.h                 |  8 ++++----
 ...TutorialReductionsVisitorsBroadcasting.dox | 19 +++++++++++++++++--
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/Eigen/src/Core/VectorwiseOp.h b/Eigen/src/Core/VectorwiseOp.h
index 7819cb489..e8a905043 100644
--- a/Eigen/src/Core/VectorwiseOp.h
+++ b/Eigen/src/Core/VectorwiseOp.h
@@ -561,7 +561,7 @@ template<typename ExpressionType, int Direction> class VectorwiseOp
   * Example: \include MatrixBase_colwise.cpp
   * Output: \verbinclude MatrixBase_colwise.out
   *
-  * \sa rowwise(), class VectorwiseOp
+  * \sa rowwise(), class VectorwiseOp, \ref TutorialReductionsVisitorsBroadcasting
   */
 template<typename Derived>
 inline const typename DenseBase<Derived>::ConstColwiseReturnType
@@ -572,7 +572,7 @@ DenseBase<Derived>::colwise() const
 
 /** \returns a writable VectorwiseOp wrapper of *this providing additional partial reduction operations
   *
-  * \sa rowwise(), class VectorwiseOp
+  * \sa rowwise(), class VectorwiseOp, \ref TutorialReductionsVisitorsBroadcasting
   */
 template<typename Derived>
 inline typename DenseBase<Derived>::ColwiseReturnType
@@ -586,7 +586,7 @@ DenseBase<Derived>::colwise()
   * Example: \include MatrixBase_rowwise.cpp
   * Output: \verbinclude MatrixBase_rowwise.out
   *
-  * \sa colwise(), class VectorwiseOp
+  * \sa colwise(), class VectorwiseOp, \ref TutorialReductionsVisitorsBroadcasting
   */
 template<typename Derived>
 inline const typename DenseBase<Derived>::ConstRowwiseReturnType
@@ -597,7 +597,7 @@ DenseBase<Derived>::rowwise() const
 
 /** \returns a writable VectorwiseOp wrapper of *this providing additional partial reduction operations
   *
-  * \sa colwise(), class VectorwiseOp
+  * \sa colwise(), class VectorwiseOp, \ref TutorialReductionsVisitorsBroadcasting
   */
 template<typename Derived>
 inline typename DenseBase<Derived>::RowwiseReturnType
diff --git a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
index e58ff6e2c..f3879b8b9 100644
--- a/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
+++ b/doc/C07_TutorialReductionsVisitorsBroadcasting.dox
@@ -191,12 +191,27 @@ This can be accomplished with:
 \verbinclude Tutorial_ReductionsVisitorsBroadcasting_broadcast_simple.out
 </td></tr></table>
 
+We can interpret the instruction <tt>mat.colwise() += v</tt> in two equivalent ways. It adds the vector \c v
+to every column of the matrix. Alternatively, it can be interpreted as repeating the vector \c v four times to
+form a four-by-two matrix which is then added to \c mat:
+\f[
+\begin{bmatrix} 1 & 2 & 6 & 9 \\ 3 & 1 & 7 & 2 \end{bmatrix}
++ \begin{bmatrix} 0 & 0 & 0 & 0 \\ 1 & 1 & 1 & 1 \end{bmatrix}
+= \begin{bmatrix} 1 & 2 & 6 & 9 \\ 4 & 2 & 8 & 3 \end{bmatrix}.
+\f]
+The operators <tt>-=</tt>, <tt>+</tt> and <tt>-</tt> can also be used column-wise and row-wise. On arrays, we 
+can also use the operators <tt>*=</tt>, <tt>/=</tt>, <tt>*</tt> and <tt>/</tt> to perform coefficient-wise 
+multiplication and division column-wise or row-wise. These operators are not available on matrices because it
+is not clear what they would do. If you want multiply column 0 of a matrix \c mat with \c v(0), column 1 with 
+\c v(1), and so on, then use <tt>mat = mat * v.asDiagonal()</tt>.
+
 It is important to point out that the vector to be added column-wise or row-wise must be of type Vector,
 and cannot be a Matrix. If this is not met then you will get compile-time error. This also means that
 broadcasting operations can only be applied with an object of type Vector, when operating with Matrix.
-The same applies for the Array class, where the equivalent for VectorXf is ArrayXf.
+The same applies for the Array class, where the equivalent for VectorXf is ArrayXf. As always, you should
+not mix arrays and matrices in the same expression.
 
-Therefore, to perform the same operation row-wise we can do:
+To perform the same operation row-wise we can do:
 
 <table class="example">
 <tr><th>Example:</th><th>Output:</th></tr>