Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r63636 - in trunk/boost/numeric/ublas: . detail
From: david.bellot_at_[hidden]
Date: 2010-07-04 17:43:46

Next message: nielsdekker_at_[hidden]: "[Boost-commit] svn:boost r63637 - branches/release/boost/utility"
Previous message: barend.gehrels_at_[hidden]: "[Boost-commit] svn:boost r63635 - sandbox/geometry/libs/geometry/test/strategies"

Author: david.bellot
Date: 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
New Revision: 63636
URL: http://svn.boost.org/trac/boost/changeset/63636

Log:
update doxygen doc

Added:
   trunk/boost/numeric/ublas/doxydoc.hpp
      - copied, changed from r63563, /branches/ublas-doxygen/doxydoc.hpp
Properties modified:
   trunk/boost/numeric/ublas/ (props changed)
Text files modified:
   trunk/boost/numeric/ublas/banded.hpp | 55 ++++
   trunk/boost/numeric/ublas/blas.hpp | 490 ++++++++++++++++++++++++++++-----------
   trunk/boost/numeric/ublas/detail/definitions.hpp | 2
   trunk/boost/numeric/ublas/doxydoc.hpp | 64 +++++
   trunk/boost/numeric/ublas/exception.hpp | 9
   trunk/boost/numeric/ublas/expression_types.hpp | 72 +++--
   trunk/boost/numeric/ublas/fwd.hpp | 6
   trunk/boost/numeric/ublas/hermitian.hpp | 35 ++
   trunk/boost/numeric/ublas/io.hpp | 112 ++++++++
   trunk/boost/numeric/ublas/lu.hpp | 5
   trunk/boost/numeric/ublas/matrix.hpp | 119 ++++++++-
   trunk/boost/numeric/ublas/matrix_proxy.hpp | 22 +
   trunk/boost/numeric/ublas/matrix_sparse.hpp | 20 +
   trunk/boost/numeric/ublas/triangular.hpp | 18 +
   trunk/boost/numeric/ublas/vector.hpp | 327 +++++++++++++++++++++++++
   trunk/boost/numeric/ublas/vector_proxy.hpp | 87 ++++++
   trunk/boost/numeric/ublas/vector_sparse.hpp | 64 ++++
   17 files changed, 1286 insertions(+), 221 deletions(-)

Modified: trunk/boost/numeric/ublas/banded.hpp
==============================================================================
--- trunk/boost/numeric/ublas/banded.hpp (original)
+++ trunk/boost/numeric/ublas/banded.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -20,7 +20,18 @@

namespace boost { namespace numeric { namespace ublas {

- // Array based banded matrix class
+ /** \brief A banded matrix of values of type \c T.
+ *
+ * For a \f$(mxn)\f$-dimensional banded matrix with \f$l\f$ lower and \f$u\f$ upper diagonals and
+ * \f$0 \leq i < m\f$ and \f$0 \leq j < n\f$, if \f$i>j+l\f$ or \f$i<j-u\f$ then \f$b_{i,j}=0\f$.
+ * The default storage for banded matrices is packed. Orientation and storage can also be specified.
+ * Default is \c row_major and and unbounded_array. It is \b not required by the storage to initialize
+ * elements of the matrix.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
+ * \tparam A the type of Storage array. Default is \c unbounded_array
+ */
 template<class T, class L, class A>
 class banded_matrix:
 public matrix_container<banded_matrix<T, L, A> > {
@@ -970,7 +981,21 @@
 typename banded_matrix<T, L, A>::const_value_type banded_matrix<T, L, A>::zero_ = value_type/*zero*/();

- // Diagonal matrix class
+ /** \brief A diagonal matrix of values of type \c T, which is a specialization of a banded matrix
+ *
+ * For a \f$(m\times m)\f$-dimensional diagonal matrix, \f$0 \leq i < m\f$ and \f$0 \leq j < m\f$,
+ * if \f$i\neq j\f$ then \f$b_{i,j}=0\f$. The default storage for diagonal matrices is packed.
+ * Orientation and storage can also be specified. Default is \c row major \c unbounded_array.
+ *
+ * As a specialization of a banded matrix, the constructor of the diagonal matrix creates
+ * a banded matrix with 0 upper and lower diagonals around the main diagonal and the matrix is
+ * obviously a square matrix. Operations are optimized based on these 2 assumptions. It is
+ * \b not required by the storage to initialize elements of the matrix.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
+ * \tparam A the type of Storage array. Default is \c unbounded_array
+ */
 template<class T, class L, class A>
 class diagonal_matrix:
 public banded_matrix<T, L, A> {
@@ -1013,7 +1038,18 @@
 }
 };

- // Banded matrix adaptor class
+ /** \brief A banded matrix adaptator: convert a any matrix into a banded matrix expression
+ *
+ * For a \f$(m\times n)\f$-dimensional matrix, the \c banded_adaptor will provide a banded matrix
+ * with \f$l\f$ lower and \f$u\f$ upper diagonals and \f$0 \leq i < m\f$ and \f$0 \leq j < n\f$,
+ * if \f$i>j+l\f$ or \f$i<j-u\f$ then \f$b_{i,j}=0\f$.
+ *
+ * Storage and location are based on those of the underlying matrix. This is important because
+ * a \c banded_adaptor does not copy the matrix data to a new place. Therefore, modifying values
+ * in a \c banded_adaptor matrix will also modify the underlying matrix too.
+ *
+ * \tparam M the type of matrix used to generate a banded matrix
+ */
 template<class M>
 class banded_adaptor:
 public matrix_expression<banded_adaptor<M> > {
@@ -1987,7 +2023,18 @@
 template<class M>
 typename banded_adaptor<M>::const_value_type banded_adaptor<M>::zero_ = value_type/*zero*/();

- // Diagonal matrix adaptor class
+ /** \brief A diagonal matrix adaptator: convert a any matrix into a diagonal matrix expression
+ *
+ * For a \f$(m\times m)\f$-dimensional matrix, the \c diagonal_adaptor will provide a diagonal matrix
+ * with \f$0 \leq i < m\f$ and \f$0 \leq j < m\f$, if \f$i\neq j\f$ then \f$b_{i,j}=0\f$.
+ *
+ * Storage and location are based on those of the underlying matrix. This is important because
+ * a \c diagonal_adaptor does not copy the matrix data to a new place. Therefore, modifying values
+ * in a \c diagonal_adaptor matrix will also modify the underlying matrix too.
+ *
+ * \tparam M the type of matrix used to generate the diagonal matrix
+ */
+
 template<class M>
 class diagonal_adaptor:
 public banded_adaptor<M> {

Modified: trunk/boost/numeric/ublas/blas.hpp
==============================================================================
--- trunk/boost/numeric/ublas/blas.hpp (original)
+++ trunk/boost/numeric/ublas/blas.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -16,89 +16,150 @@
#include <boost/numeric/ublas/traits.hpp>

namespace boost { namespace numeric { namespace ublas {
+

+ /** Interface and implementation of BLAS level 1
+ * This includes functions which perform \b vector-vector operations.
+ * More information about BLAS can be found at
+ * http://en.wikipedia.org/wiki/BLAS
+ */
 namespace blas_1 {

- /** \namespace boost::numeric::ublas::blas_1
- \brief wrapper functions for level 1 blas
- */
-
-
- /** \brief 1-Norm: \f$\sum_i |x_i|\f$
- \ingroup blas1
- */
+ /** 1-Norm: \f$\sum_i |x_i|\f$ (also called \f$\mathcal{L}_1\f$ or Manhattan norm)
+ *
+ * \param v a vector or vector expression
+ * \return the 1-Norm with type of the vector's type
+ *
+ * \tparam V type of the vector (not needed by default)
+ */
 template<class V>
 typename type_traits<typename V::value_type>::real_type
 asum (const V &v) {
 return norm_1 (v);
 }
- /** \brief 2-Norm: \f$\sum_i |x_i|^2\f$
- \ingroup blas1
- */
+
+ /** 2-Norm: \f$\sum_i |x_i|^2\f$ (also called \f$\mathcal{L}_2\f$ or Euclidean norm)
+ *
+ * \param v a vector or vector expression
+ * \return the 2-Norm with type of the vector's type
+ *
+ * \tparam V type of the vector (not needed by default)
+ */
 template<class V>
 typename type_traits<typename V::value_type>::real_type
 nrm2 (const V &v) {
 return norm_2 (v);
 }
- /** \brief element with larges absolute value: \f$\max_i |x_i|\f$
- \ingroup blas1
- */
+
+ /** Infinite-norm: \f$\max_i |x_i|\f$ (also called \f$\mathcal{L}_\infty\f$ norm)
+ *
+ * \param v a vector or vector expression
+ * \return the Infinite-Norm with type of the vector's type
+ *
+ * \tparam V type of the vector (not needed by default)
+ */
 template<class V>
 typename type_traits<typename V::value_type>::real_type
 amax (const V &v) {
 return norm_inf (v);
 }

- /** \brief inner product of vectors \a v1 and \a v2
- \ingroup blas1
- */
+ /** Inner product of vectors \f$v_1\f$ and \f$v_2\f$
+ *
+ * \param v1 first vector of the inner product
+ * \param v2 second vector of the inner product
+ * \return the inner product of the type of the most generic type of the 2 vectors
+ *
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2 type of second vector (not needed by default)
+ */
 template<class V1, class V2>
 typename promote_traits<typename V1::value_type, typename V2::value_type>::promote_type
 dot (const V1 &v1, const V2 &v2) {
 return inner_prod (v1, v2);
 }

- /** \brief copy vector \a v2 to \a v1
- \ingroup blas1
- */
+ /** Copy vector \f$v_2\f$ to \f$v_1\f$
+ *
+ * \param v1 target vector
+ * \param v2 source vector
+ * \return a reference to the target vector
+ *
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2 type of second vector (not needed by default)
+ */
 template<class V1, class V2>
- V1 &
- copy (V1 &v1, const V2 &v2) {
+ V1 & copy (V1 &v1, const V2 &v2)
+ {
 return v1.assign (v2);
 }

- /** \brief swap vectors \a v1 and \a v2
- \ingroup blas1
- */
- template<class V1, class V2>
- void swap (V1 &v1, V2 &v2) {
+ /** Swap vectors \f$v_1\f$ and \f$v_2\f$
+ *
+ * \param v1 first vector
+ * \param v2 second vector
+ *
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2 type of second vector (not needed by default)
+ */
+ template<class V1, class V2>
+ void swap (V1 &v1, V2 &v2)
+ {
 v1.swap (v2);
 }

- /** \brief scale vector \a v with scalar \a t
- \ingroup blas1
- */
+ /** scale vector \f$v\f$ with scalar \f$t\f$
+ *
+ * \param v vector to be scaled
+ * \param t the scalar
+ * \return \c t*v
+ *
+ * \tparam V type of the vector (not needed by default)
+ * \tparam T type of the scalar (not needed by default)
+ */
 template<class V, class T>
- V &
- scal (V &v, const T &t) {
+ V & scal (V &v, const T &t)
+ {
 return v *= t;
 }

- /** \brief compute \a v1 = \a v1 + \a t * \a v2
- \ingroup blas1
- */
+ /** Compute \f$v_1= v_1 + t.v_2\f$
+ *
+ * \param v1 target and first vector
+ * \param t the scalar
+ * \param v2 second vector
+ * \return a reference to the first and target vector
+ *
+ * \tparam V1 type of the first vector (not needed by default)
+ * \tparam T type of the scalar (not needed by default)
+ * \tparam V2 type of the second vector (not needed by default)
+ */
 template<class V1, class T, class V2>
- V1 &
- axpy (V1 &v1, const T &t, const V2 &v2) {
+ V1 & axpy (V1 &v1, const T &t, const V2 &v2)
+ {
 return v1.plus_assign (t * v2);
 }

- /** \brief apply plane rotation
- \ingroup blas1
- */
+ /** Performs rotation of points in the plane and assign the result to the first vector
+ *
+ * Each point is defined as a pair \c v1(i) and \c v2(i), being respectively
+ * the \f$x\f$ and \f$y\f$ coordinates. The parameters \c t1 and \t2 are respectively
+ * the cosine and sine of the angle of the rotation.
+ * Results are not returned but directly written into \c v1.
+ *
+ * \param t1 cosine of the rotation
+ * \param v1 vector of \f$x\f$ values
+ * \param t2 sine of the rotation
+ * \param v2 vector of \f$y\f$ values
+ *
+ * \tparam T1 type of the cosine value (not needed by default)
+ * \tparam V1 type of the \f$x\f$ vector (not needed by default)
+ * \tparam T2 type of the sine value (not needed by default)
+ * \tparam V2 type of the \f$y\f$ vector (not needed by default)
+ */
 template<class T1, class V1, class T2, class V2>
- void
- rot (const T1 &t1, V1 &v1, const T2 &t2, V2 &v2) {
+ void rot (const T1 &t1, V1 &v1, const T2 &t2, V2 &v2)
+ {
 typedef typename promote_traits<typename V1::value_type, typename V2::value_type>::promote_type promote_type;
 vector<promote_type> vt (t1 * v1 + t2 * v2);
 v2.assign (- t2 * v1 + t1 * v2);
@@ -107,46 +168,82 @@

 }

+ /** \brief Interface and implementation of BLAS level 2
+ * This includes functions which perform \b matrix-vector operations.
+ * More information about BLAS can be found at
+ * http://en.wikipedia.org/wiki/BLAS
+ */
 namespace blas_2 {

- /** \namespace boost::numeric::ublas::blas_2
- \brief wrapper functions for level 2 blas
- */
-
- /** \brief multiply vector \a v with triangular matrix \a m
- \ingroup blas2
- \todo: check that matrix is really triangular
- */
+ /** \brief multiply vector \c v with triangular matrix \c m
+ *
+ * \param v a vector
+ * \param m a triangular matrix
+ * \return the result of the product
+ *
+ * \tparam V type of the vector (not needed by default)
+ * \tparam M type of the matrix (not needed by default)
+ */
 template<class V, class M>
- V &
- tmv (V &v, const M &m) {
+ V & tmv (V &v, const M &m)
+ {
 return v = prod (m, v);
 }

- /** \brief solve \a m \a x = \a v in place, \a m is triangular matrix
- \ingroup blas2
- */
+ /** \brief solve \f$m.x = v\f$ in place, where \c m is a triangular matrix
+ *
+ * \param v a vector
+ * \param m a matrix
+ * \param C (this parameter is not needed)
+ * \return a result vector from the above operation
+ *
+ * \tparam V type of the vector (not needed by default)
+ * \tparam M type of the matrix (not needed by default)
+ * \tparam C n/a
+ */
 template<class V, class M, class C>
- V &
- tsv (V &v, const M &m, C) {
+ V & tsv (V &v, const M &m, C)
+ {
 return v = solve (m, v, C ());
 }

- /** \brief compute \a v1 = \a t1 * \a v1 + \a t2 * (\a m * \a v2)
- \ingroup blas2
- */
+ /** \brief compute \f$ v_1 = t_1.v_1 + t_2.(m.v_2)\f$, a general matrix-vector product
+ *
+ * \param v1 a vector
+ * \param t1 a scalar
+ * \param t2 another scalar
+ * \param m a matrix
+ * \param v2 another vector
+ * \return the vector \c v1 with the result from the above operation
+ *
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam T1 type of first scalar (not needed by default)
+ * \tparam T2 type of second scalar (not needed by default)
+ * \tparam M type of matrix (not needed by default)
+ * \tparam V2 type of second vector (not needed by default)
+ */
 template<class V1, class T1, class T2, class M, class V2>
- V1 &
- gmv (V1 &v1, const T1 &t1, const T2 &t2, const M &m, const V2 &v2) {
+ V1 & gmv (V1 &v1, const T1 &t1, const T2 &t2, const M &m, const V2 &v2)
+ {
 return v1 = t1 * v1 + t2 * prod (m, v2);
 }

- /** \brief rank 1 update: \a m = \a m + \a t * (\a v1 * \a v2T)
- \ingroup blas2
- */
+ /** \brief Rank 1 update: \f$ m = m + t.(v_1.v_2^T)\f$
+ *
+ * \param m a matrix
+ * \param t a scalar
+ * \param v1 a vector
+ * \param v2 another vector
+ * \return a matrix with the result from the above operation
+ *
+ * \tparam M type of matrix (not needed by default)
+ * \tparam T type of scalar (not needed by default)
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2type of second vector (not needed by default)
+ */
 template<class M, class T, class V1, class V2>
- M &
- gr (M &m, const T &t, const V1 &v1, const V2 &v2) {
+ M & gr (M &m, const T &t, const V1 &v1, const V2 &v2)
+ {
#ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG
 return m += t * outer_prod (v1, v2);
#else
@@ -154,24 +251,41 @@
#endif
 }

- /** \brief symmetric rank 1 update: \a m = \a m + \a t * (\a v * \a vT)
- \ingroup blas2
- */
+ /** \brief symmetric rank 1 update: \f$m = m + t.(v.v^T)\f$
+ *
+ * \param m a matrix
+ * \param t a scalar
+ * \param v a vector
+ * \return a matrix with the result from the above operation
+ *
+ * \tparam M type of matrix (not needed by default)
+ * \tparam T type of scalar (not needed by default)
+ * \tparam V type of vector (not needed by default)
+ */
 template<class M, class T, class V>
- M &
- sr (M &m, const T &t, const V &v) {
+ M & sr (M &m, const T &t, const V &v)
+ {
#ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG
 return m += t * outer_prod (v, v);
#else
 return m = m + t * outer_prod (v, v);
#endif
 }
- /** \brief hermitian rank 1 update: \a m = \a m + \a t * (\a v * \a vH)
- \ingroup blas2
- */
+
+ /** \brief hermitian rank 1 update: \f$m = m + t.(v.v^H)\f$
+ *
+ * \param m a matrix
+ * \param t a scalar
+ * \param v a vector
+ * \return a matrix with the result from the above operation
+ *
+ * \tparam M type of matrix (not needed by default)
+ * \tparam T type of scalar (not needed by default)
+ * \tparam V type of vector (not needed by default)
+ */
 template<class M, class T, class V>
- M &
- hr (M &m, const T &t, const V &v) {
+ M & hr (M &m, const T &t, const V &v)
+ {
#ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG
 return m += t * outer_prod (v, conj (v));
#else
@@ -179,27 +293,45 @@
#endif
 }

- /** \brief symmetric rank 2 update: \a m = \a m + \a t *
- (\a v1 * \a v2T + \a v2 * \a v1T)
- \ingroup blas2
+ /** \brief symmetric rank 2 update: \f$ m=m+ t.(v_1.v_2^T + v_2.v_1^T)\f$
+ *
+ * \param m a matrix
+ * \param t a scalar
+ * \param v1 a vector
+ * \param v2 another vector
+ * \return a matrix with the result from the above operation
+ *
+ * \tparam M type of matrix (not needed by default)
+ * \tparam T type of scalar (not needed by default)
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2type of second vector (not needed by default)
 */
 template<class M, class T, class V1, class V2>
- M &
- sr2 (M &m, const T &t, const V1 &v1, const V2 &v2) {
+ M & sr2 (M &m, const T &t, const V1 &v1, const V2 &v2)
+ {
#ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG
 return m += t * (outer_prod (v1, v2) + outer_prod (v2, v1));
#else
 return m = m + t * (outer_prod (v1, v2) + outer_prod (v2, v1));
#endif
 }
- /** \brief hermitian rank 2 update: \a m = \a m +
- \a t * (\a v1 * \a v2H)
- + \a v2 * (\a t * \a v1)H)
- \ingroup blas2
- */
+
+ /** \brief hermitian rank 2 update: \f$m=m+t.(v_1.v_2^H) + v_2.(t.v_1)^H)\f$
+ *
+ * \param m a matrix
+ * \param t a scalar
+ * \param v1 a vector
+ * \param v2 another vector
+ * \return a matrix with the result from the above operation
+ *
+ * \tparam M type of matrix (not needed by default)
+ * \tparam T type of scalar (not needed by default)
+ * \tparam V1 type of first vector (not needed by default)
+ * \tparam V2type of second vector (not needed by default)
+ */
 template<class M, class T, class V1, class V2>
- M &
- hr2 (M &m, const T &t, const V1 &v1, const V2 &v2) {
+ M & hr2 (M &m, const T &t, const V1 &v1, const V2 &v2)
+ {
#ifndef BOOST_UBLAS_SIMPLE_ET_DEBUG
 return m += t * outer_prod (v1, conj (v2)) + type_traits<T>::conj (t) * outer_prod (v2, conj (v1));
#else
@@ -209,82 +341,158 @@

 }

+ /** \brief Interface and implementation of BLAS level 3
+ * This includes functions which perform \b matrix-matrix operations.
+ * More information about BLAS can be found at
+ * http://en.wikipedia.org/wiki/BLAS
+ */
 namespace blas_3 {

- /** \namespace boost::numeric::ublas::blas_3
- \brief wrapper functions for level 3 blas
- */
-
- /** \brief triangular matrix multiplication
- \ingroup blas3
- */
+ /** \brief triangular matrix multiplication \f$m_1=t.m_2.m_3\f$ where \f$m_2\f$ and \f$m_3\f$ are triangular
+ *
+ * \param m1 a matrix for storing result
+ * \param t a scalar
+ * \param m2 a triangular matrix
+ * \param m3 a triangular matrix
+ * \return the matrix \c m1
+ *
+ * \tparam M1 type of the result matrix (not needed by default)
+ * \tparam T type of the scalar (not needed by default)
+ * \tparam M2 type of the first triangular matrix (not needed by default)
+ * \tparam M3 type of the second triangular matrix (not needed by default)
+ *
+ */
 template<class M1, class T, class M2, class M3>
- M1 &
- tmm (M1 &m1, const T &t, const M2 &m2, const M3 &m3) {
+ M1 & tmm (M1 &m1, const T &t, const M2 &m2, const M3 &m3)
+ {
 return m1 = t * prod (m2, m3);
 }

- /** \brief triangular solve \a m2 * \a x = \a t * \a m1 in place,
- \a m2 is a triangular matrix
- \ingroup blas3
- */
+ /** \brief triangular solve \f$ m_2.x = t.m_1\f$ in place, \f$m_2\f$ is a triangular matrix
+ *
+ * \param m1 a matrix
+ * \param t a scalar
+ * \param m2 a triangular matrix
+ * \param C (not used)
+ * \return the \f$m_1\f$ matrix
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T type of the scalar (not needed by default)
+ * \tparam M2 type of the triangular matrix (not needed by default)
+ * \tparam C (n/a)
+ */
 template<class M1, class T, class M2, class C>
- M1 &
- tsm (M1 &m1, const T &t, const M2 &m2, C) {
+ M1 & tsm (M1 &m1, const T &t, const M2 &m2, C)
+ {
 return m1 = solve (m2, t * m1, C ());
 }

- /** \brief general matrix multiplication
- \ingroup blas3
- */
+ /** \brief general matrix multiplication \f$m_1=t_1.m_1 + t_2.m_2.m_3\f$
+ *
+ * \param m1 first matrix
+ * \param t1 first scalar
+ * \param t2 second scalar
+ * \param m2 second matrix
+ * \param m3 third matrix
+ * \return the matrix \c m1
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T1 type of the first scalar (not needed by default)
+ * \tparam T2 type of the second scalar (not needed by default)
+ * \tparam M2 type of the second matrix (not needed by default)
+ * \tparam M3 type of the third matrix (not needed by default)
+ */
 template<class M1, class T1, class T2, class M2, class M3>
- M1 &
- gmm (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) {
+ M1 & gmm (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3)
+ {
 return m1 = t1 * m1 + t2 * prod (m2, m3);
 }

- /** \brief symmetric rank k update: \a m1 = \a t * \a m1 +
- \a t2 * (\a m2 * \a m2T)
- \ingroup blas3
- \todo use opb_prod()
- */
+ /** \brief symmetric rank \a k update: \f$m_1=t.m_1+t_2.(m_2.m_2^T)\f$
+ *
+ * \param m1 first matrix
+ * \param t1 first scalar
+ * \param t2 second scalar
+ * \param m2 second matrix
+ * \return matrix \c m1
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T1 type of the first scalar (not needed by default)
+ * \tparam T2 type of the second scalar (not needed by default)
+ * \tparam M2 type of the second matrix (not needed by default)
+ * \todo use opb_prod()
+ */
 template<class M1, class T1, class T2, class M2>
- M1 &
- srk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) {
+ M1 & srk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2)
+ {
 return m1 = t1 * m1 + t2 * prod (m2, trans (m2));
 }
- /** \brief hermitian rank k update: \a m1 = \a t * \a m1 +
- \a t2 * (\a m2 * \a m2H)
- \ingroup blas3
- \todo use opb_prod()
- */
+
+ /** \brief hermitian rank \a k update: \f$m_1=t.m_1+t_2.(m_2.m2^H)\f$
+ *
+ * \param m1 first matrix
+ * \param t1 first scalar
+ * \param t2 second scalar
+ * \param m2 second matrix
+ * \return matrix \c m1
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T1 type of the first scalar (not needed by default)
+ * \tparam T2 type of the second scalar (not needed by default)
+ * \tparam M2 type of the second matrix (not needed by default)
+ * \todo use opb_prod()
+ */
 template<class M1, class T1, class T2, class M2>
- M1 &
- hrk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2) {
+ M1 & hrk (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2)
+ {
 return m1 = t1 * m1 + t2 * prod (m2, herm (m2));
 }

- /** \brief generalized symmetric rank k update:
- \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3T)
- + \a t2 * (\a m3 * \a m2T)
- \ingroup blas3
- \todo use opb_prod()
- */
+ /** \brief generalized symmetric rank \a k update: \f$m_1=t_1.m_1+t_2.(m_2.m3^T)+t_2.(m_3.m2^T)\f$
+ *
+ * \param m1 first matrix
+ * \param t1 first scalar
+ * \param t2 second scalar
+ * \param m2 second matrix
+ * \param m3 third matrix
+ * \return matrix \c m1
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T1 type of the first scalar (not needed by default)
+ * \tparam T2 type of the second scalar (not needed by default)
+ * \tparam M2 type of the second matrix (not needed by default)
+ * \tparam M3 type of the third matrix (not needed by default)
+ * \todo use opb_prod()
+ */
 template<class M1, class T1, class T2, class M2, class M3>
- M1 &
- sr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) {
+ M1 & sr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3)
+ {
 return m1 = t1 * m1 + t2 * (prod (m2, trans (m3)) + prod (m3, trans (m2)));
 }
- /** \brief generalized hermitian rank k update:
- \a m1 = \a t1 * \a m1 + \a t2 * (\a m2 * \a m3H)
- + (\a m3 * (\a t2 * \a m2)H)
- \ingroup blas3
- \todo use opb_prod()
- */
+
+ /** \brief generalized hermitian rank \a k update: * \f$m_1=t_1.m_1+t_2.(m_2.m_3^H)+(m_3.(t_2.m_2)^H)\f$
+ *
+ * \param m1 first matrix
+ * \param t1 first scalar
+ * \param t2 second scalar
+ * \param m2 second matrix
+ * \param m3 third matrix
+ * \return matrix \c m1
+ *
+ * \tparam M1 type of the first matrix (not needed by default)
+ * \tparam T1 type of the first scalar (not needed by default)
+ * \tparam T2 type of the second scalar (not needed by default)
+ * \tparam M2 type of the second matrix (not needed by default)
+ * \tparam M3 type of the third matrix (not needed by default)
+ * \todo use opb_prod()
+ */
 template<class M1, class T1, class T2, class M2, class M3>
- M1 &
- hr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3) {
- return m1 = t1 * m1 + t2 * prod (m2, herm (m3)) + type_traits<T2>::conj (t2) * prod (m3, herm (m2));
+ M1 & hr2k (M1 &m1, const T1 &t1, const T2 &t2, const M2 &m2, const M3 &m3)
+ {
+ return m1 =
+ t1 * m1
+ + t2 * prod (m2, herm (m3))
+ + type_traits<T2>::conj (t2) * prod (m3, herm (m2));
 }

 }
@@ -292,5 +500,3 @@
}}}

#endif
-
-

Modified: trunk/boost/numeric/ublas/detail/definitions.hpp
==============================================================================
--- trunk/boost/numeric/ublas/detail/definitions.hpp (original)
+++ trunk/boost/numeric/ublas/detail/definitions.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -80,7 +80,7 @@
 closure_type lval_;
 };

- // Improve syntax of effcient assignment where no aliases of LHS appear on the RHS
+ // Improve syntax of efficient assignment where no aliases of LHS appear on the RHS
 // noalias(lhs) = rhs_expression
 template <class C>
 BOOST_UBLAS_INLINE

Copied: trunk/boost/numeric/ublas/doxydoc.hpp (from r63563, /branches/ublas-doxygen/doxydoc.hpp)
==============================================================================
--- /branches/ublas-doxygen/doxydoc.hpp (original)
+++ trunk/boost/numeric/ublas/doxydoc.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1 +1,65 @@
+//
+// Copyright (c) 2010
+// David Bellot
+//
+// Distributed under the Boost Software License, Version 1.0. (See
+// accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+//
+// And we acknowledge the support from all contributors.

+/** \mainpage BOOST uBLAS: a Linear Algebra Library
+ *
+ * This is the API Reference Documentation.
+ *
+ * For introduction, documentations and tutorial, please refer
+ * to http://www.boost.org/doc/libs/1_44_0/libs/numeric/ublas/doc/index.htm
+ *
+ * \section main_classes Main classes
+ *
+ * \subsection listvector Vectors
+ * - \link #boost::numeric::ublas::vector vector \endlink
+ * - \link #boost::numeric::ublas::bounded_vector bounded_vector \endlink
+ * - \link #boost::numeric::ublas::zero_vector zero_vector \endlink
+ * - \link #boost::numeric::ublas::unit_vector unit_vector \endlink
+ * - \link #boost::numeric::ublas::scalar_vector scalar_vector \endlink
+ * - \link #boost::numeric::ublas::c_vector c_vector \endlink
+ * - \link #boost::numeric::ublas::vector_slice vector_slice \endlink
+ * - \link #boost::numeric::ublas::vector_range vector_range \endlink
+ * - \link #boost::numeric::ublas::vector_indirect vector_indirect \endlink
+ * - \link #boost::numeric::ublas::mapped_vector mapped_vector \endlink
+ * - \link #boost::numeric::ublas::compressed_vector compressed_vector \endlink
+ * - \link #boost::numeric::ublas::coordinate_vector coordinate_vector \endlink
+ * - \link #boost::numeric::ublas::matrix_row matrix_row \endlink
+ * - \link #boost::numeric::ublas::matrix_column matrix_column \endlink
+ *
+ * \subsection listmatrix Matrices
+ * - \link #boost::numeric::ublas::matrix matrix \endlink
+ * - \link #boost::numeric::ublas::banded_matrix banded_matrix \endlink
+ * - \link #boost::numeric::ublas::diagonal_matrix diagonal_matrix \endlink
+ * - \link #boost::numeric::ublas::banded_adaptor banded_adaptor \endlink
+ * - \link #boost::numeric::ublas::diagonal_adaptor diagonal_adaptor \endlink
+ * - \link #boost::numeric::ublas::hermitian_matrix hermitian_matrix \endlink
+ * - \link #boost::numeric::ublas::hermitian_adaptor hermitian_adaptor \endlink
+ * - \link #boost::numeric::ublas::symmetric_matrix symmetric_matrix \endlink
+ * - \link #boost::numeric::ublas::symmetric_adaptor symmetric_adaptor \endlink
+ * - \link #boost::numeric::ublas::triangular_matrix triangular_matrix \endlink
+ * - \link #boost::numeric::ublas::triangular_adaptor triangular_adaptor \endlink
+ * - \link #boost::numeric::ublas::vector_of_vector vector_of_vector \endlink
+ * - \link #boost::numeric::ublas::bounded_matrix bounded_matrix \endlink
+ * - \link #boost::numeric::ublas::zero_matrix zero_matrix \endlink
+ * - \link #boost::numeric::ublas::identity_matrix identity_matrix \endlink
+ * - \link #boost::numeric::ublas::scalar_matrix scalar_matrix \endlink
+ * - \link #boost::numeric::ublas::c_matrix c_matrix \endlink
+ * - \link #boost::numeric::ublas::matrix_vector_range matrix_vector_range \endlink
+ * - \link #boost::numeric::ublas::matrix_vector_slice matrix_vector_slice \endlink
+ * - \link #boost::numeric::ublas::matrix_vector_indirect matrix_vector_indirect \endlink
+ * - \link #boost::numeric::ublas::matrix_range matrix_range \endlink
+ * - \link #boost::numeric::ublas::matrix_slice matrix_slice \endlink
+ * - \link #boost::numeric::ublas::matrix_indirect matrix_indirect \endlink
+ * - \link #boost::numeric::ublas::mapped_matrix mapped_matrix \endlink
+ * - \link #boost::numeric::ublas::mapped_vector_of_mapped_vector mapped_vector_of_mapped_vector \endlink
+ * - \link #boost::numeric::ublas::compressed_matrix compressed_matrix \endlink
+ * - \link #boost::numeric::ublas::coordinate_matrix coordinate_matrix \endlink
+ * - \link #boost::numeric::ublas::generalized_vector_of_vector generalized_vector_of_vector \endlink
+ */

Modified: trunk/boost/numeric/ublas/exception.hpp
==============================================================================
--- trunk/boost/numeric/ublas/exception.hpp (original)
+++ trunk/boost/numeric/ublas/exception.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -26,10 +26,13 @@

namespace boost { namespace numeric { namespace ublas {

+ /** \brief Exception raised when a division by zero occurs
+ */
     struct divide_by_zero
#if ! defined (BOOST_NO_EXCEPTIONS) && ! defined (BOOST_UBLAS_NO_EXCEPTIONS)
         // Inherit from standard exceptions as requested during review.
- : public std::runtime_error {
+ : public std::runtime_error
+ {
         explicit divide_by_zero (const char *s = "divide by zero") :
             std::runtime_error (s) {}
         void raise () {
@@ -47,6 +50,8 @@
#endif
     };

+ /** \brief Expception raised when some interal errors occurs like computations errors, zeros values where you should not have zeros, etc...
+ */
     struct internal_logic
#if ! defined (BOOST_NO_EXCEPTIONS) && ! defined (BOOST_UBLAS_NO_EXCEPTIONS)
         // Inherit from standard exceptions as requested during review.
@@ -113,6 +118,8 @@
#endif
     };

+ /**
+ */
     struct bad_size
#if ! defined (BOOST_NO_EXCEPTIONS) && ! defined (BOOST_UBLAS_NO_EXCEPTIONS)
         // Inherit from standard exceptions as requested during review.

Modified: trunk/boost/numeric/ublas/expression_types.hpp
==============================================================================
--- trunk/boost/numeric/ublas/expression_types.hpp (original)
+++ trunk/boost/numeric/ublas/expression_types.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -22,8 +22,13 @@

namespace boost { namespace numeric { namespace ublas {

- // Base class for uBLAS staticaly derived expressions - see the Barton Nackman trick
- // Provides numeric properties for linear algebra
+ /** \brief Base class for uBLAS staticaly derived expressions using the the Barton Nackman trick
+ *
+ * This class provides the numeric properties for linear algebra.
+ * This is a NonAssignable class
+ *
+ * \tparam E an expression type
+ */
 template<class E>
 class ublas_expression {
 public:
@@ -42,11 +47,16 @@
 };

- // Base class for Scalar Expression models -
- // it does not model the Scalar Expression concept but all derived types should.
- // The class defines a common base type and some common interface for all
- // statically derived Scalar Expression classes
- // We implement the casts to the statically derived type.
+ /** \brief Base class for Scalar Expression models
+ *
+ * It does not model the Scalar Expression concept but all derived types should.
+ * The class defines a common base type and some common interface for all statically
+ * derived Scalar Expression classes.
+ *
+ * We implement the casts to the statically derived type.
+ *
+ * \tparam E an expression type
+ */
 template<class E>
 class scalar_expression:
 public ublas_expression<E> {
@@ -163,11 +173,13 @@
 };

- // Base class for Vector Expression models -
- // it does not model the Vector Expression concept but all derived types should.
- // The class defines a common base type and some common interface for all
- // statically derived Vector Expression classes
- // We implement the casts to the statically derived type.
+ /** \brief Base class for Vector Expression models
+ *
+ * it does not model the Vector Expression concept but all derived types should.
+ * The class defines a common base type and some common interface for all
+ * statically derived Vector Expression classes.
+ * We implement the casts to the statically derived type.
+ */
 template<class E>
 class vector_expression:
 public ublas_expression<E> {
@@ -255,11 +267,13 @@
#endif
 };

- // Base class for Vector container models -
- // it does not model the Vector concept but all derived types should.
- // The class defines a common base type and some common interface for all
- // statically derived Vector classes
- // We implement the casts to the statically derived type.
+ /** \brief Base class for Vector container models
+ *
+ * it does not model the Vector concept but all derived types should.
+ * The class defines a common base type and some common interface for all
+ * statically derived Vector classes
+ * We implement the casts to the statically derived type.
+ */
 template<class C>
 class vector_container:
 public vector_expression<C> {
@@ -283,11 +297,13 @@
 };

- // Base class for Matrix Expression models -
- // it does not model the Matrix Expression concept but all derived types should.
- // The class defines a common base type and some common interface for all
- // statically derived Matrix Expression classes
- // We implement the casts to the statically derived type.
+ /** \brief Base class for Matrix Expression models
+ *
+ * it does not model the Matrix Expression concept but all derived types should.
+ * The class defines a common base type and some common interface for all
+ * statically derived Matrix Expression classes
+ * We implement the casts to the statically derived type.
+ */
 template<class E>
 class matrix_expression:
 public ublas_expression<E> {
@@ -458,11 +474,13 @@
 }
#endif

- // Base class for Matrix container models -
- // it does not model the Matrix concept but all derived types should.
- // The class defines a common base type and some common interface for all
- // statically derived Matrix classes
- // We implement the casts to the statically derived type.
+ /** \brief Base class for Matrix container models
+ *
+ * it does not model the Matrix concept but all derived types should.
+ * The class defines a common base type and some common interface for all
+ * statically derived Matrix classes
+ * We implement the casts to the statically derived type.
+ */
 template<class C>
 class matrix_container:
 public matrix_expression<C> {

Modified: trunk/boost/numeric/ublas/fwd.hpp
==============================================================================
--- trunk/boost/numeric/ublas/fwd.hpp (original)
+++ trunk/boost/numeric/ublas/fwd.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1,6 +1,6 @@
//
-// Copyright (c) 2000-2002
-// Joerg Walter, Mathias Koch
+// Copyright (c) 2000-2010
+// Joerg Walter, Mathias Koch, David Bellot
//
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at
@@ -10,6 +10,8 @@
// GeNeSys mbH & Co. KG in producing this work.
//

+/// \file fwd.hpp is essentially used to forward declare the main types
+
#ifndef BOOST_UBLAS_FWD_H
#define BOOST_UBLAS_FWD_H

Modified: trunk/boost/numeric/ublas/hermitian.hpp
==============================================================================
--- trunk/boost/numeric/ublas/hermitian.hpp (original)
+++ trunk/boost/numeric/ublas/hermitian.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1,6 +1,6 @@
//
-// Copyright (c) 2000-2002
-// Joerg Walter, Mathias Koch
+// Copyright (c) 2000-2010
+// Joerg Walter, Mathias Koch, David Bellot
//
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at
@@ -222,8 +222,24 @@
 };

#endif
-
- // Array based hermitian matrix class
+ /** \brief A hermitian matrix of values of type \c T
+ *
+ * For a \f$(n \times n)\f$-dimensional matrix and \f$ 0 \leq i < n, 0 \leq j < n\f$, every element
+ * \f$m_{i,j}\f$ is mapped to the \f$(i.n + j)\f$-th element of the container for row major orientation
+ * or the \f$(i + j.m)\f$-th element of the container for column major orientation. And
+ * \f$\forall i,j\f$, \f$m_{i,j} = \overline{m_{i,j}}\f$.
+ *
+ * Orientation and storage can also be specified, otherwise a row major and unbounded array are used.
+ * It is \b not required by the storage to initialize elements of the matrix.
+ * Moreover, only the given triangular matrix is stored and the storage of hermitian matrices is packed.
+ *
+ * See http://en.wikipedia.org/wiki/Hermitian_matrix for more details on hermitian matrices.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam TRI the type of triangular matrix is either \c lower or \c upper. Default is \c lower
+ * \tparam L the storage organization. It is either \c row_major or \c column_major. Default is \c row_major
+ * \tparam A the type of Storage array. Default is \unbounded_array.
+ */
 template<class T, class TRI, class L, class A>
 class hermitian_matrix:
 public matrix_container<hermitian_matrix<T, TRI, L, A> > {
@@ -1127,8 +1143,15 @@
 array_type data_;
 };

-
- // Hermitian matrix adaptor class
+ /** \brief A Hermitian matrix adaptator: convert a any matrix into a Hermitian matrix expression
+ *
+ * For a \f$(m\times n)\f$-dimensional matrix, the \c hermitian_adaptor will provide a hermitian matrix.
+ * Storage and location are based on those of the underlying matrix. This is important because
+ * a \c hermitian_adaptor does not copy the matrix data to a new place. Therefore, modifying values
+ * in a \c hermitian_adaptor matrix will also modify the underlying matrix too.
+ *
+ * \tparam M the type of matrix used to generate a hermitian matrix
+ */
 template<class M, class TRI>
 class hermitian_adaptor:
 public matrix_expression<hermitian_adaptor<M, TRI> > {

Modified: trunk/boost/numeric/ublas/io.hpp
==============================================================================
--- trunk/boost/numeric/ublas/io.hpp (original)
+++ trunk/boost/numeric/ublas/io.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1,6 +1,6 @@
//
-// Copyright (c) 2000-2002
-// Joerg Walter, Mathias Koch
+// Copyright (c) 2000-2010
+// Joerg Walter, Mathias Koch, David Bellot
//
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at
@@ -21,6 +21,28 @@

namespace boost { namespace numeric { namespace ublas {

+ /** \brief output stream operator for vector expressions
+ *
+ * Any vector expressions can be written to a standard output stream
+ * as defined in the C++ standard library. For example:
+ * \code
+ * vector<float> v1(3),v2(3);
+ * for(size_t i=0; i<3; i++)
+ * {
+ * v1(i) = i+0.2;
+ * v2(i) = i+0.3;
+ * }
+ * cout << v1+v2 << endl;
+ * \endcode
+ * will display the some of the 2 vectors like this:
+ * \code
+ * [3](0.5,2.5,4.5)
+ * \endcode
+ *
+ * \param os is a standard basic output stream
+ * \param v is a vector expression
+ * \return a reference to the resulting output stream
+ */
 template<class E, class T, class VE>
 // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
 std::basic_ostream<E, T> &operator << (std::basic_ostream<E, T> &os,
@@ -40,6 +62,28 @@
 return os << s.str ().c_str ();
 }

+ /** \brief input stream operator for vectors
+ *
+ * This is used to feed in vectors with data stored as an ASCII representation
+ * from a standard input stream.
+ *
+ * From a file or any valid stream, the format is:
+ * \c [<vector size>](<data1>,<data2>,...<dataN>) like for example:
+ * \code
+ * [5](1,2.1,3.2,3.14,0.2)
+ * \endcode
+ *
+ * You can use it like this
+ * \code
+ * my_input_stream >> my_vector;
+ * \endcode
+ *
+ * You can only put data into a valid \c vector<> not a \c vector_expression
+ *
+ * \param is is a standard basic input stream
+ * \param v is a vector
+ * \return a reference to the resulting input stream
+ */
 template<class E, class T, class VT, class VA>
 // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
 std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,
@@ -78,6 +122,29 @@
 return is;
 }

+ /** \brief output stream operator for matrix expressions
+ *
+ * it outpus the content of a \f$(M \times N)\f$ matrix to a standard output
+ * stream using the following format:
+ * \c[<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>))
+ *
+ * For example:
+ * \code
+ * matrix<float> m(3,3) = scalar_matrix<float>(3,3,1.0) - diagonal_matrix<float>(3,3,1.0);
+ * cout << m << endl;
+ * \encode
+ * will display
+ * \code
+ * [3,3]((0,1,1),(1,0,1),(1,1,0))
+ * \endcode
+ * This output is made for storing and retrieving matrices in a simple way but you can
+ * easily recognize the following:
+ * \f[ \left( \begin{array}{ccc} 1 & 1 & 1\\ 1 & 1 & 1\\ 1 & 1 & 1 \end{array} \right) - \left( \begin{array}{ccc} 1 & 0 & 0\\ 0 & 1 & 0\\ 0 & 0 & 1 \end{array} \right) = \left( \begin{array}{ccc} 0 & 1 & 1\\ 1 & 0 & 1\\ 1 & 1 & 0 \end{array} \right) \f]
+ *
+ * \param os is a standard basic output stream
+ * \param m is a matrix expression
+ * \return a reference to the resulting output stream
+ */
 template<class E, class T, class ME>
 // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
 std::basic_ostream<E, T> &operator << (std::basic_ostream<E, T> &os,
@@ -110,6 +177,25 @@
 return os << s.str ().c_str ();
 }

+ /** \brief input stream operator for matrices
+ *
+ * This is used to feed in matrices with data stored as an ASCII representation
+ * from a standard input stream.
+ *
+ * From a file or any valid standard stream, the format is:
+ * \c[<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>))
+ *
+ * You can use it like this
+ * \code
+ * my_input_stream >> my_matrix;
+ * \endcode
+ *
+ * You can only put data into a valid \c matrix<> not a \c matrix_expression
+ *
+ * \param is is a standard basic input stream
+ * \param m is a matrix
+ * \return a reference to the resulting input stream
+ */
 template<class E, class T, class MT, class MF, class MA>
 // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
 std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,
@@ -171,7 +257,27 @@
 return is;
 }

- // Special input operator for symmetrix_matrix
+ /** \brief special input stream operator for symmetric matrices
+ *
+ * This is used to feed in symmetric matrices with data stored as an ASCII
+ * representation from a standard input stream.
+ *
+ * You can simply write your matrices in a file or any valid stream and read them again
+ * at a later time with this function. The format is the following:
+ * \code [<rows>,<columns>]((<m00>,<m01>,...,<m0N>),...,(<mM0>,<mM1>,...,<mMN>)) \endcode
+ *
+ * You can use it like this
+ * \code
+ * my_input_stream >> my_symmetric_matrix;
+ * \endcode
+ *
+ * You can only put data into a valid \c symmetric_matrix<>, not in a \c matrix_expression
+ * This function also checks that input data form a valid symmetric matrix
+ *
+ * \param is is a standard basic input stream
+ * \param m is a \c symmetric_matrix
+ * \return a reference to the resulting input stream
+ */
 template<class E, class T, class MT, class MF1, class MF2, class MA>
 // BOOST_UBLAS_INLINE This function seems to be big. So we do not let the compiler inline it.
 std::basic_istream<E, T> &operator >> (std::basic_istream<E, T> &is,

Modified: trunk/boost/numeric/ublas/lu.hpp
==============================================================================
--- trunk/boost/numeric/ublas/lu.hpp (original)
+++ trunk/boost/numeric/ublas/lu.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -23,6 +23,11 @@

namespace boost { namespace numeric { namespace ublas {

+ /** \brief
+ *
+ * \tparam T
+ * \tparam A
+ */
 template<class T = std::size_t, class A = unbounded_array<T> >
 class permutation_matrix:
 public vector<T, A> {

Modified: trunk/boost/numeric/ublas/matrix.hpp
==============================================================================
--- trunk/boost/numeric/ublas/matrix.hpp (original)
+++ trunk/boost/numeric/ublas/matrix.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1,6 +1,6 @@
//
-// Copyright (c) 2000-2007
-// Joerg Walter, Mathias Koch, Gunter Winkler
+// Copyright (c) 2000-2010
+// Joerg Walter, Mathias Koch, Gunter Winkler, David Bellot
//
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at
@@ -22,7 +22,22 @@

// Iterators based on ideas of Jeremy Siek

-namespace boost { namespace numeric { namespace ublas {
+namespace boost { namespace numeric {
+
+ /** \brief main namespace of uBLAS.
+ *
+ * Use this namespace for all operations with uBLAS. It can also be abbreviated with
+ * \code namespace ublas = boost::numeric::ublas; \endcode
+ *
+ * A common practice is to bring this namespace into the current scope with
+ * \code using namespace boost::numeric::ublas; \endcode.
+ *
+ * However, be warned that using the ublas namespace and the std::vector at the same time can lead to the compiler to confusion.
+ * The solution is simply to prefix each ublas vector like \c boost::numeric::ublas::vector<T>. If you think it's too long to
+ * write, you can define a new namespace like \c namespace ublas = boost::numeric::ublas and then just declare your vectors
+ * with \c ublas::vector<T>. STL vectors will be declared as vector<T>. No need to prefix with \c std::
+ */
+ namespace ublas {

 namespace detail {
 using namespace boost::numeric::ublas;
@@ -57,8 +72,20 @@
 }
 }

-
- // Array based matrix class
+ /** \brief A dense matrix of values of type \c T.
+ *
+ * For a \f$(m \times n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$ m_{i,j} \f$ is mapped to
+ * the \f$(i.n + j)\f$-th element of the container for row major orientation or the \f$ (i + j.m) \f$-th element of
+ * the container for column major orientation. In a dense matrix all elements are represented in memory in a
+ * contiguous chunk of memory by definition.
+ *
+ * Orientation and storage can also be specified, otherwise a \c row_major and \c unbounded_array are used. It is \b not
+ * required by the storage to initialize elements of the matrix.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
+ * \tparam A the type of Storage array. Default is \c unbounded_array
+ */
 template<class T, class L, class A>
 class matrix:
 public matrix_container<matrix<T, L, A> > {
@@ -981,8 +1008,22 @@
 array_type data_;
 };

-
- // Bounded matrix class
+ /** \brief A dense matrix of values of type \c T with a variable size bounded to a maximum of \f$M\f$ by \f$N\f$.
+ *
+ * For a \f$(m \times n)\f$-dimensional matrix and \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j}\f$ is mapped
+ * to the \f$(i.n + j)\f$-th element of the container for row major orientation or the \f$(i + j.m)\f$-th element
+ * of the container for column major orientation. Finally in a dense matrix all elements are represented in memory
+ * in a contiguous chunk of memory.
+ *
+ * Orientation can be specified. Default is \c row_major
+ * The default constructor creates the matrix with size \f$M\f$ by \f$N\f$. Elements are constructed by the storage
+ * type \c bounded_array, which need not initialise their value.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam M maximum and default number of rows (if not specified at construction)
+ * \tparam N maximum and default number of columns (if not specified at construction)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
+ */
 template<class T, std::size_t M, std::size_t N, class L>
 class bounded_matrix:
 public matrix<T, L, bounded_array<T, M * N> > {
@@ -1050,8 +1091,21 @@
 }
 };

-
- // Array based matrix class
+ /** \brief A dense matrix of values of type \c T stored as a vector of vectors.
+ *
+ * Rows or columns are not stored into contiguous chunks of memory but data inside rows (or columns) are.
+ * Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used.
+ * The data is stored as a vector of vectors, meaning that rows or columns might not be stored into contiguous chunks
+ * of memory. Orientation and storage can also be specified, otherwise a row major and unbounded arrays are used.
+ * The storage type defaults to \c unbounded_array<unbounded_array<T>> and orientation is \c row_major. It is \b not
+ * required by the storage to initialize elements of the matrix. For a \f$(m \times n)\f$-dimensional matrix and
+ * \f$ 0 \leq i < m, 0 \leq j < n\f$, every element \f$m_{i,j}\f$ is mapped to the \f$(i.n + j)\f$-th element of the
+ * container for row major orientation or the \f$(i + j.m)\f$-th element of the container for column major orientation.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. By default it is \c row_major
+ * \tparam A the type of Storage array. By default, it is an \unbounded_array<unbounder_array<T>>
+ */
 template<class T, class L, class A>
 class vector_of_vector:
 public matrix_container<vector_of_vector<T, L, A> > {
@@ -2032,7 +2086,14 @@
 };

- // Zero matrix class
+ /** \brief A matrix with all values of type \c T equal to zero
+ *
+ * Changing values does not affect the matrix, however assigning it to a normal matrix will put zero
+ * everywhere in the target matrix. All accesses are constant time, due to the trivial value.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam ALLOC an allocator for storing the zero element. By default, a standar allocator is used.
+ */
 template<class T, class ALLOC>
 class zero_matrix:
 public matrix_container<zero_matrix<T, ALLOC> > {
@@ -2411,8 +2472,15 @@
 template<class T, class ALLOC>
 const typename zero_matrix<T, ALLOC>::value_type zero_matrix<T, ALLOC>::zero_ = T(/*zero*/);

-
- // Identity matrix class
+ /** \brief An identity matrix with values of type \c T
+ *
+ * Elements or cordinates \f$(i,i)\f$ are equal to 1 (one) and all others to 0 (zero).
+ * Changing values does not affect the matrix, however assigning it to a normal matrix will
+ * make the matrix equal to an identity matrix. All accesses are constant du to the trivial values.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam ALLOC an allocator for storing the zeros and one elements. By default, a standar allocator is used.
+ */
 template<class T, class ALLOC>
 class identity_matrix:
 public matrix_container<identity_matrix<T, ALLOC> > {
@@ -2821,7 +2889,14 @@
 const typename identity_matrix<T, ALLOC>::value_type identity_matrix<T, ALLOC>::one_ (1); // ISSUE: need 'one'-traits here

- // Scalar matrix class
+ /** \brief A matrix with all values of type \c T equal to the same value
+ *
+ * Changing one value has the effect of changing all the values. Assigning it to a normal matrix will copy
+ * the same value everywhere in this matrix. All accesses are constant time, due to the trivial value.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam ALLOC an allocator for storing the unique value. By default, a standar allocator is used.
+ */
 template<class T, class ALLOC>
 class scalar_matrix:
 public matrix_container<scalar_matrix<T, ALLOC> > {
@@ -3275,7 +3350,23 @@
 };

- // Array based matrix class
+ /** \brief An array based matrix class which size is defined at type specification or object instanciation
+ *
+ * This matrix is directly based on a predefined C-style arry of data, thus providing the fastest
+ * implementation possible. The constraint is that dimensions of the matrix must be specified at
+ * the instanciation or the type specification.
+ *
+ * For instance, \code typedef c_matrix<double,4,4> my_4by4_matrix \endcode
+ * defines a 4 by 4 double-precision matrix. You can also instantiate it directly with
+ * \code c_matrix<int,8,5> my_fast_matrix \endcode. This will make a 8 by 5 integer matrix. The
+ * price to pay for this speed is that you cannot resize it to a size larger than the one defined
+ * in the template parameters. In the previous example, a size of 4 by 5 or 3 by 2 is acceptable,
+ * but a new size of 9 by 5 or even 10 by 10 will raise a bad_size() exception.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam N the default maximum number of rows
+ * \tparam M the default maximum number of columns
+ */
 template<class T, std::size_t N, std::size_t M>
 class c_matrix:
 public matrix_container<c_matrix<T, N, M> > {

Modified: trunk/boost/numeric/ublas/matrix_proxy.hpp
==============================================================================
--- trunk/boost/numeric/ublas/matrix_proxy.hpp (original)
+++ trunk/boost/numeric/ublas/matrix_proxy.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -22,7 +22,8 @@

namespace boost { namespace numeric { namespace ublas {

- // Matrix based row vector class
+ /** \brief
+ */
 template<class M>
 class matrix_row:
 public vector_expression<matrix_row<M> > {
@@ -1856,6 +1857,7 @@
 : vector_temporary_traits< M > {} ;

 // Matrix based vector indirection class
+
 template<class M, class IA>
 class matrix_vector_indirect:
 public vector_expression<matrix_vector_indirect<M, IA> > {
@@ -4162,6 +4164,24 @@
 // Matrix based indirection class
 // Contributed by Toon Knapen.
 // Extended and optimized by Kresimir Fresl.
+ /** \brief A matrix referencing a non continuous submatrix of elements given another matrix of indices.
+ *
+ * It is the most general version of any submatrices because it uses another matrix of indices to reference
+ * the submatrix.
+ *
+ * The matrix of indices can be of any type with the restriction that its elements must be
+ * type-compatible with the size_type \c of the container. In practice, the following are good candidates:
+ * - \c boost::numeric::ublas::indirect_array<A> where \c A can be \c int, \c size_t, \c long, etc...
+ * - \c boost::numeric::ublas::matrix<int> can work too (\c int can be replaced by another integer type)
+ * - etc...
+ *
+ * An indirect matrix can be used as a normal matrix in any expression. If the specified indirect matrix
+ * falls outside that of the indices of the matrix, then the \c matrix_indirect is not a well formed
+ * \i Matrix \i Expression and access to an element outside of indices of the matrix is \b undefined.
+ *
+ * \tparam V the type of the referenced matrix, for example \c matrix<double>)
+ * \tparam IA the type of index matrix. Default is \c ublas::indirect_array<>
+ */
 template<class M, class IA>
 class matrix_indirect:
 public matrix_expression<matrix_indirect<M, IA> > {

Modified: trunk/boost/numeric/ublas/matrix_sparse.hpp
==============================================================================
--- trunk/boost/numeric/ublas/matrix_sparse.hpp (original)
+++ trunk/boost/numeric/ublas/matrix_sparse.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -246,8 +246,24 @@

#endif

-
- // Index map based sparse matrix class
+ /** \brief Index map based sparse matrix of values of type \c T
+ *
+ * This class represents a matrix by using a \c key to value mapping. The default type is
+ * \code template<class T, class L = row_major, class A = map_std<std::size_t, T> > class mapped_matrix; \endcode
+ * So, by default a STL map container is used to associate keys and values. The key is computed depending on
+ * the layout type \c L as \code key = layout_type::element(i, size1_, j, size2_); \endcode
+ * which means \code key = (i*size2+j) \endcode for a row major matrix.
+ * Limitations: The matrix size must not exceed \f$(size1*size2) < \f$ \code std::limits<std::size_t> \endcode.
+ * The \ref find1() and \ref find2() operations have a complexity of at least \f$\mathcal{O}(log(nnz))\f$, depending
+ * on the efficiency of \c std::lower_bound on the key set of the map.
+ * Orientation and storage can also be specified, otherwise a row major orientation is used.
+ * It is \b not required by the storage to initialize elements of the matrix. By default, the orientation is \c row_major.
+ *
+ * \sa fwd.hpp, storage_sparse.hpp
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. By default it is \c row_major
+ */
 template<class T, class L, class A>
 class mapped_matrix:
 public matrix_container<mapped_matrix<T, L, A> > {

Modified: trunk/boost/numeric/ublas/triangular.hpp
==============================================================================
--- trunk/boost/numeric/ublas/triangular.hpp (original)
+++ trunk/boost/numeric/ublas/triangular.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -57,7 +57,23 @@
 }
 }

- // Array based triangular matrix class
+ /** \brief A triangular matrix of values of type \c T.
+ *
+ * For a \f$(n \times n )\f$-dimensional lower triangular matrix and if \f$0 \leq i < n\f$, \f$0 \leq j < n\f$ and \f$i>j\f$ holds,
+ * \f$m_{i,j}=0\f$. Furthermore if \f$m_{i,i}=1\f$, the matrix is called unit lower triangular.
+ *
+ * For a \f$(n \times n )\f$-dimensional upper triangular matrix and if \f$0 \leq i < n\f$, \f$0 \leq j < n\f$ and \f$i<j\f$ holds,
+ * \f$m_{i,j}=0\f$. Furthermore if \f$m_{i,i}=1\f$, the matrix is called unit upper triangular.
+ *
+ * The default storage for triangular matrices is packed. Orientation and storage can also be specified.
+ * Default is \c row_major and and unbounded_array. It is \b not required by the storage to initialize
+ * elements of the matrix.
+ *
+ * \tparam T the type of object stored in the matrix (like double, float, complex, etc...)
+ * \tparam TRI the type of the triangular matrix. It can either be \c lower or \c upper. Default is \c lower
+ * \tparam L the storage organization. It can be either \c row_major or \c column_major. Default is \c row_major
+ * \tparam A the type of Storage array. Default is \c unbounded_array
+ */
 template<class T, class TRI, class L, class A>
 class triangular_matrix:
 public matrix_container<triangular_matrix<T, TRI, L, A> > {

Modified: trunk/boost/numeric/ublas/vector.hpp
==============================================================================
--- trunk/boost/numeric/ublas/vector.hpp (original)
+++ trunk/boost/numeric/ublas/vector.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -1,6 +1,6 @@
//
-// Copyright (c) 2000-2002
-// Joerg Walter, Mathias Koch
+// Copyright (c) 2000-2010
+// Joerg Walter, Mathias Koch, David Bellot
//
// Distributed under the Boost Software License, Version 1.0. (See
// accompanying file LICENSE_1_0.txt or copy at
@@ -8,8 +8,10 @@
//
// The authors gratefully acknowledge the support of
// GeNeSys mbH & Co. KG in producing this work.
-// ----------------------------------------------------------------
-//
+//
+// And we acknowledge the support from all contributors.
+
+/// \file vector.hpp Definition for the class vector and its derivative

#ifndef _BOOST_UBLAS_VECTOR_
#define _BOOST_UBLAS_VECTOR_
@@ -20,11 +22,20 @@
#include <boost/serialization/collection_size_type.hpp>
#include <boost/serialization/nvp.hpp>

+
// Iterators based on ideas of Jeremy Siek

namespace boost { namespace numeric { namespace ublas {

- // Array based vector class
+ /** \brief A dense vector of values of type \c T.
+ *
+ * For a \f$n\f$-dimensional vector \f$v\f$ and \f$0\leq i < n\f$ every element \f$v_i\f$ is mapped
+ * to the \f$i\f$-th element of the container. A storage type \c A can be specified which defaults to \c unbounded_array.
+ * Elements are constructed by \c A, which need not initialise their value.
+ *
+ * \tparam T type of the objects stored in the vector (like int, double, complex,...)
+ * \tparam A The type of the storage array of the vector. Default is \c unbounded_array<T>. \c <bounded_array<T> and \c std::vector<T> can also be used
+ */
 template<class T, class A>
 class vector:
 public vector_container<vector<T, A> > {
@@ -34,7 +45,8 @@
#ifdef BOOST_UBLAS_ENABLE_PROXY_SHORTCUTS
 using vector_container<self_type>::operator ();
#endif
- typedef typename A::size_type size_type;
+
+ typedef typename A::size_type size_type;
 typedef typename A::difference_type difference_type;
 typedef T value_type;
 typedef typename type_traits<T>::const_reference const_reference;
@@ -48,27 +60,60 @@
 typedef dense_tag storage_category;

 // Construction and destruction
+
+ /// \brief Constructor of a vector
+ /// By default it is empty, i.e. \c size()==0.
 BOOST_UBLAS_INLINE
 vector ():
 vector_container<self_type> (),
 data_ () {}
+
+ /// \brief Constructor of a vector with a predefined size
+ /// By default, its elements are initialized to 0.
+ /// \param size initial size of the vector
 explicit BOOST_UBLAS_INLINE
 vector (size_type size):
 vector_container<self_type> (),
 data_ (size) {
 }
+
+ /// \brief Constructor of a vector by copying from another container
+ /// This type has the generic name \c array_typ within the vector definition.
+ /// \param size initial size of the vector \bug this value is not used
+ /// \param data container of type \c A
+ /// \todo remove this definition because \c size is not used
 BOOST_UBLAS_INLINE
 vector (size_type size, const array_type &data):
 vector_container<self_type> (),
 data_ (data) {}
+
+ /// \brief Constructor of a vector by copying from another container
+ /// This type has the generic name \c array_typ within the vector definition.
+ /// \param data container of type \c A
+ BOOST_UBLAS_INLINE
+ vector (const array_type &data):
+ vector_container<self_type> (),
+ data_ (data) {}
+
+ /// \brief Constructor of a vector with a predefined size and a unique initial value
+ /// \param size of the vector
+ /// \param init value to assign to each element of the vector
 BOOST_UBLAS_INLINE
 vector (size_type size, const value_type &init):
 vector_container<self_type> (),
 data_ (size, init) {}
+
+ /// \brief Copy-constructor of a vector
+ /// \param v is the vector to be duplicated
 BOOST_UBLAS_INLINE
 vector (const vector &v):
 vector_container<self_type> (),
 data_ (v.data_) {}
+
+ /// \brief Copy-constructor of a vector from a vector_expression
+ /// Depending on the vector_expression, this constructor can have the cost of the computations
+ /// of the expression (trivial to say it, but it is to take into account in your complexity calculations).
+ /// \param ae the vector_expression which values will be duplicated into the vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector (const vector_expression<AE> &ae):
@@ -77,33 +122,58 @@
 vector_assign<scalar_assign> (*this, ae);
 }

+ // -----------------------
 // Random Access Container
+ // -----------------------
+
+ /// \brief Return the maximum size of the data container.
+ /// Return the upper bound (maximum size) on the data container. Depending on the container, it can be bigger than the current size of the vector.
 BOOST_UBLAS_INLINE
 size_type max_size () const {
 return data_.max_size ();
 }

+ /// \brief Return true if the vector is empty (\c size==0)
+ /// \return \c true if empty, \c false otherwise
 BOOST_UBLAS_INLINE
 bool empty () const {
 return data_.size () == 0;
 }
+
+ // ---------
 // Accessors
+ // ---------
+
+ /// \brief Return the size of the vector
 BOOST_UBLAS_INLINE
 size_type size () const {
 return data_.size ();
 }

+ // -----------------
 // Storage accessors
+ // -----------------
+
+ /// \brief Return a \c const reference to the container. Useful to access data directly for specific type of container.
 BOOST_UBLAS_INLINE
 const array_type &data () const {
 return data_;
 }
+
+ /// \brief Return a reference to the container. Useful to speed-up write operations to the data in very specific case.
 BOOST_UBLAS_INLINE
 array_type &data () {
 return data_;
 }

+ // --------
 // Resizing
+ // --------
+
+ /// \brief Resize the vector
+ /// Resize the vector to a new size. If \c preserve is true, data are copied otherwise data are lost. If the new size is bigger, the remaining values are filled in with the initial value (0 by default) in the case of \c unbounded_array, which is the container by default. If the new size is smaller, last values are lost. This behaviour can be different if you explicitely specify another type of container.
+ /// \param size new size of the vector
+ /// \param preserve if true, keep values
 BOOST_UBLAS_INLINE
 void resize (size_type size, bool preserve = true) {
 if (preserve)
@@ -112,46 +182,85 @@
 data ().resize (size);
 }

+ // ---------------
 // Element support
+ // ---------------
+
+ /// \brief Return a pointer to the element \f$i\f$
+ /// \param i index of the element
+ // XXX this semantic is not the one expected by the name of this method
 BOOST_UBLAS_INLINE
 pointer find_element (size_type i) {
 return const_cast<pointer> (const_cast<const self_type&>(*this).find_element (i));
 }
+
+ /// \brief Return a const pointer to the element \f$i\f$
+ /// \param i index of the element
+ // XXX this semantic is not the one expected by the name of this method
 BOOST_UBLAS_INLINE
 const_pointer find_element (size_type i) const {
 return & (data () [i]);
 }

+ // --------------
 // Element access
+ // --------------
+
+ /// \brief Return a const reference to the element \f$i\f$
+ /// Return a const reference to the element \f$i\f$. With some compilers, this notation will be faster than \c[i]
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 const_reference operator () (size_type i) const {
 return data () [i];
 }
+
+ /// \brief Return a reference to the element \f$i\f$
+ /// Return a reference to the element \f$i\f$. With some compilers, this notation will be faster than \c[i]
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 reference operator () (size_type i) {
 return data () [i];
 }

+ /// \brief Return a const reference to the element \f$i\f$
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 const_reference operator [] (size_type i) const {
 return (*this) (i);
 }
+
+ /// \brief Return a reference to the element \f$i\f$
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 reference operator [] (size_type i) {
 return (*this) (i);
 }

+ // ------------------
 // Element assignment
+ // ------------------
+
+ /// \brief Set element \f$i\f$ to the value \c t
+ /// \param i index of the element
+ /// \param t reference to the value to be set
+ // XXX semantic of this is to insert a new element and therefore size=size+1 ?
 BOOST_UBLAS_INLINE
 reference insert_element (size_type i, const_reference t) {
 return (data () [i] = t);
 }
+
+ /// \brief Set element \f$i\f$ to the \e zero value
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 void erase_element (size_type i) {
 data () [i] = value_type/*zero*/();
 }

+ // -------
 // Zeroing
+ // -------
+
+ /// \brief Clear the vector, i.e. set all values to the \c zero value.
 BOOST_UBLAS_INLINE
 void clear () {
 std::fill (data ().begin (), data ().end (), value_type/*zero*/());
@@ -160,6 +269,9 @@
 // Assignment
#ifdef BOOST_UBLAS_MOVE_SEMANTICS

+ /// \brief Assign a full vector (\e RHS-vector) to the current vector (\e LHS-vector)
+ /// \param v is the source vector
+ /// \return a reference to a vector (i.e. the destination vector)
 /*! @note "pass by value" the key idea to enable move semantics */
 BOOST_UBLAS_INLINE
 vector &operator = (vector v) {
@@ -167,12 +279,20 @@
 return *this;
 }
#else
+ /// \brief Assign a full vector (\e RHS-vector) to the current vector (\e LHS-vector)
+ /// \param v is the source vector
+ /// \return a reference to a vector (i.e. the destination vector)
 BOOST_UBLAS_INLINE
 vector &operator = (const vector &v) {
 data () = v.data ();
 return *this;
 }
#endif
+
+ /// \brief Assign a full vector (\e RHS-vector) to the current vector (\e LHS-vector)
+ /// Assign a full vector (\e RHS-vector) to the current vector (\e LHS-vector). This method does not create any temporary.
+ /// \param v is the source vector container
+ /// \return a reference to a vector (i.e. the destination vector)
 template<class C> // Container assignment without temporary
 BOOST_UBLAS_INLINE
 vector &operator = (const vector_container<C> &v) {
@@ -180,17 +300,33 @@
 assign (v);
 return *this;
 }
+
+ /// \brief Assign a full vector (\e RHS-vector) to the current vector (\e LHS-vector)
+ /// \param v is the source vector
+ /// \return a reference to a vector (i.e. the destination vector)
 BOOST_UBLAS_INLINE
 vector &assign_temporary (vector &v) {
 swap (v);
 return *this;
 }
+
+ /// \brief Assign the result of a vector_expression to the vector
+ /// Assign the result of a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &operator = (const vector_expression<AE> &ae) {
 self_type temporary (ae);
 return assign_temporary (temporary);
 }
+
+ /// \brief Assign the result of a vector_expression to the vector
+ /// Assign the result of a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &assign (const vector_expression<AE> &ae) {
@@ -198,49 +334,106 @@
 return *this;
 }

+ // -------------------
 // Computed assignment
+ // -------------------
+
+ /// \brief Assign the sum of the vector and a vector_expression to the vector
+ /// Assign the sum of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// A temporary is created for the computations.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &operator += (const vector_expression<AE> &ae) {
 self_type temporary (*this + ae);
 return assign_temporary (temporary);
 }
+
+ /// \brief Assign the sum of the vector and a vector_expression to the vector
+ /// Assign the sum of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class C> // Container assignment without temporary
 BOOST_UBLAS_INLINE
 vector &operator += (const vector_container<C> &v) {
 plus_assign (v);
 return *this;
 }
+
+ /// \brief Assign the sum of the vector and a vector_expression to the vector
+ /// Assign the sum of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &plus_assign (const vector_expression<AE> &ae) {
 vector_assign<scalar_plus_assign> (*this, ae);
 return *this;
 }
+
+ /// \brief Assign the difference of the vector and a vector_expression to the vector
+ /// Assign the difference of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// A temporary is created for the computations.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &operator -= (const vector_expression<AE> &ae) {
 self_type temporary (*this - ae);
 return assign_temporary (temporary);
 }
+
+ /// \brief Assign the difference of the vector and a vector_expression to the vector
+ /// Assign the difference of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class C> // Container assignment without temporary
 BOOST_UBLAS_INLINE
 vector &operator -= (const vector_container<C> &v) {
 minus_assign (v);
 return *this;
 }
+
+ /// \brief Assign the difference of the vector and a vector_expression to the vector
+ /// Assign the difference of the vector and a vector_expression to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param ae is a const reference to the vector_expression
+ /// \return a reference to the resulting vector
 template<class AE>
 BOOST_UBLAS_INLINE
 vector &minus_assign (const vector_expression<AE> &ae) {
 vector_assign<scalar_minus_assign> (*this, ae);
 return *this;
 }
+
+ /// \brief Assign the product of the vector and a scalar to the vector
+ /// Assign the product of the vector and a scalar to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param at is a const reference to the scalar
+ /// \return a reference to the resulting vector
 template<class AT>
 BOOST_UBLAS_INLINE
 vector &operator *= (const AT &at) {
 vector_assign_scalar<scalar_multiplies_assign> (*this, at);
 return *this;
 }
+
+ /// \brief Assign the division of the vector by a scalar to the vector
+ /// Assign the division of the vector by a scalar to the vector. This is lazy-compiled and will be optimized out by the compiler on any type of expression.
+ /// No temporary is created. Computations are done and stored directly into the resulting vector.
+ /// \tparam AE is the type of the vector_expression
+ /// \param at is a const reference to the scalar
+ /// \return a reference to the resulting vector
 template<class AT>
 BOOST_UBLAS_INLINE
 vector &operator /= (const AT &at) {
@@ -248,13 +441,22 @@
 return *this;
 }

+ // --------
 // Swapping
+ // --------
+
+ /// \brief Swap the content of the vector with another vector
+ /// \param v is the vector to be swapped with
 BOOST_UBLAS_INLINE
 void swap (vector &v) {
 if (this != &v) {
 data ().swap (v.data ());
 }
 }
+
+ /// \brief Swap the content of two vectors
+ /// \param v1 is the first vector. It takes values from v2
+ /// \param v2 is the second vector It takes values from v1
 BOOST_UBLAS_INLINE
 friend void swap (vector &v1, vector &v2) {
 v1.swap (v2);
@@ -275,7 +477,12 @@
 class iterator;
#endif

+ // --------------
 // Element lookup
+ // --------------
+
+ /// \brief Return a const iterator to the element \e i
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 const_iterator find (size_type i) const {
#ifndef BOOST_UBLAS_USE_INDEXED_ITERATOR
@@ -284,6 +491,9 @@
 return const_iterator (*this, i);
#endif
 }
+
+ /// \brief Return an iterator to the element \e i
+ /// \param i index of the element
 BOOST_UBLAS_INLINE
 iterator find (size_type i) {
#ifndef BOOST_UBLAS_USE_INDEXED_ITERATOR
@@ -304,7 +514,11 @@
 typedef typename vector::const_reference reference;
 typedef const typename vector::pointer pointer;

+ // ----------------------------
 // Construction and destruction
+ // ----------------------------
+
+
 BOOST_UBLAS_INLINE
 const_iterator ():
 container_const_reference<self_type> (), it_ () {}
@@ -315,45 +529,69 @@
 const_iterator (const typename self_type::iterator &it): // ISSUE vector:: stops VC8 using std::iterator here
 container_const_reference<self_type> (it ()), it_ (it.it_) {}

+ // ----------
 // Arithmetic
+ // ----------
+
+ /// \brief Increment by 1 the position of the iterator
+ /// \return a reference to the const iterator
 BOOST_UBLAS_INLINE
 const_iterator &operator ++ () {
 ++ it_;
 return *this;
 }
+
+ /// \brief Decrement by 1 the position of the iterator
+ /// \return a reference to the const iterator
 BOOST_UBLAS_INLINE
 const_iterator &operator -- () {
 -- it_;
 return *this;
 }
+
+ /// \brief Increment by \e n the position of the iterator
+ /// \return a reference to the const iterator
 BOOST_UBLAS_INLINE
 const_iterator &operator += (difference_type n) {
 it_ += n;
 return *this;
 }
+
+ /// \brief Decrement by \e n the position of the iterator
+ /// \return a reference to the const iterator
 BOOST_UBLAS_INLINE
 const_iterator &operator -= (difference_type n) {
 it_ -= n;
 return *this;
 }
+
+ /// \brief Return the different in number of positions between 2 iterators
 BOOST_UBLAS_INLINE
 difference_type operator - (const const_iterator &it) const {
 BOOST_UBLAS_CHECK (&(*this) () == &it (), external_logic ());
 return it_ - it.it_;
 }

- // Dereference
+ /// \brief Dereference an iterator
+ /// Dereference an iterator: a bounds' check is done before returning the value. A bad_index() expection is returned if out of bounds.
+ /// \return a const reference to the value pointed by the iterator
 BOOST_UBLAS_INLINE
 const_reference operator * () const {
 BOOST_UBLAS_CHECK (it_ >= (*this) ().begin ().it_ && it_ < (*this) ().end ().it_, bad_index ());
 return *it_;
 }
+
+ /// \brief Dereference an iterator at the n-th forward value
+ /// Dereference an iterator at the n-th forward value, that is the value pointed by iterator+n.
+ /// A bounds' check is done before returning the value. A bad_index() expection is returned if out of bounds.
+ /// \return a const reference
 BOOST_UBLAS_INLINE
 const_reference operator [] (difference_type n) const {
 return *(it_ + n);
 }

 // Index
+ /// \brief return the index of the element referenced by the iterator
 BOOST_UBLAS_INLINE
 size_type index () const {
 BOOST_UBLAS_CHECK (it_ >= (*this) ().begin ().it_ && it_ < (*this) ().end ().it_, bad_index ());
@@ -362,6 +600,7 @@

 // Assignment
 BOOST_UBLAS_INLINE
+ /// \brief assign the value of an iterator to the iterator
 const_iterator &operator = (const const_iterator &it) {
 container_const_reference<self_type>::assign (&it ());
 it_ = it.it_;
@@ -369,11 +608,17 @@
 }

 // Comparison
+ /// \brief compare the value of two itetarors
+ /// \return true if they reference the same element
 BOOST_UBLAS_INLINE
 bool operator == (const const_iterator &it) const {
 BOOST_UBLAS_CHECK (&(*this) () == &it (), external_logic ());
 return it_ == it.it_;
 }
+
+
+ /// \brief compare the value of two iterators
+ /// \return return true if the left-hand-side iterator refers to a value placed before the right-hand-side iterator
 BOOST_UBLAS_INLINE
 bool operator < (const const_iterator &it) const {
 BOOST_UBLAS_CHECK (&(*this) () == &it (), external_logic ());
@@ -387,10 +632,13 @@
 };
#endif

+ /// \brief return an iterator on the first element of the vector
 BOOST_UBLAS_INLINE
 const_iterator begin () const {
 return find (0);
 }
+
+ /// \brief return an iterator after the last element of the vector
 BOOST_UBLAS_INLINE
 const_iterator end () const {
 return find (data_.size ());
@@ -488,10 +736,13 @@
 };
#endif

+ /// \brief Return an iterator on the first element of the vector
 BOOST_UBLAS_INLINE
 iterator begin () {
 return find (0);
 }
+
+ /// \brief Return an iterator at the end of the vector
 BOOST_UBLAS_INLINE
 iterator end () {
 return find (data_.size ());
@@ -501,24 +752,37 @@
 typedef reverse_iterator_base<const_iterator> const_reverse_iterator;
 typedef reverse_iterator_base<iterator> reverse_iterator;

+ /// \brief Return a const reverse iterator before the first element of the reversed vector (i.e. end() of normal vector)
 BOOST_UBLAS_INLINE
 const_reverse_iterator rbegin () const {
 return const_reverse_iterator (end ());
 }
+
+ /// \brief Return a const reverse iterator on the end of the reverse vector (i.e. first element of the normal vector)
 BOOST_UBLAS_INLINE
 const_reverse_iterator rend () const {
 return const_reverse_iterator (begin ());
 }
+
+ /// \brief Return a const reverse iterator before the first element of the reversed vector (i.e. end() of normal vector)
 BOOST_UBLAS_INLINE
 reverse_iterator rbegin () {
 return reverse_iterator (end ());
 }
+
+ /// \brief Return a const reverse iterator on the end of the reverse vector (i.e. first element of the normal vector)
 BOOST_UBLAS_INLINE
 reverse_iterator rend () {
 return reverse_iterator (begin ());
 }

+ // -------------
 // Serialization
+ // -------------
+
+ /// Serialize a vector into and archive as defined in Boost
+ /// \param ar Archive object. Can be a flat file, an XML file or any other stream
+ /// \param file_version Optional file version (not yet used)
 template<class Archive>
 void serialize(Archive & ar, const unsigned int /* file_version */){
 ar & serialization::make_nvp("data",data_);
@@ -529,7 +793,13 @@
 };

+ // --------------------
 // Bounded vector class
+ // --------------------
+
+ /// \brief a dense vector of values of type \c T, of variable size but with maximum \f$N\f$.
+ /// A dense vector of values of type \c T, of variable size but with maximum \f$N\f$. The default constructor
+ /// creates the vector with size \f$N\f$. Elements are constructed by the storage type \c bounded_array, which \b need \b not \b initialise their value.
 template<class T, std::size_t N>
 class bounded_vector:
 public vector<T, bounded_array<T, N> > {
@@ -597,7 +867,14 @@
 };

+ // -----------------
 // Zero vector class
+ // -----------------
+
+ /// \brief A zero vector of type \c T and a given \c size
+ /// A zero vector of type \c T and a given \c size. This is a virtual vector in the sense that no memory is allocated
+ /// for storing the zero values: it still acts like any other vector. However assigning values to it will not change the zero
+ /// vector into a normal vector. It must first be assigned to another normal vector by any suitable means. Its memory footprint is constant.
 template<class T, class ALLOC>
 class zero_vector:
 public vector_container<zero_vector<T, ALLOC> > {
@@ -798,6 +1075,11 @@

 // Unit vector class
+ /// \brief unit_vector represents a canonical unit vector
+ /// unit_vector represents a canonical unit vector. The \e k-th unit vector of dimension \f$n\f$ holds 0 for every value \f$u_i\f$ s.t. \f$i \neq k\f$ and 1 when \f$i=k\f$.
+ /// At construction, the value \e k is given after the dimension of the vector.
+ /// \tparam T is the type of elements in the vector. They must be 0 and 1 assignable in order for the vector to have its unit-vector semantic.
+ /// \tparam ALLOC a specific allocator can be specified if needed. Most of the time this parameter is omited.
 template<class T, class ALLOC>
 class unit_vector:
 public vector_container<unit_vector<T, ALLOC> > {
@@ -818,36 +1100,55 @@
 typedef sparse_tag storage_category;

 // Construction and destruction
+ /// \brief Simple constructor with dimension and index 0
 BOOST_UBLAS_INLINE
 unit_vector ():
 vector_container<self_type> (),
 size_ (0), index_ (0) {}
+
+ /// \brief Constructor of unit_vector
+ /// \param size is the dimension of the vector
+ /// \param index is the order of the vector
 BOOST_UBLAS_INLINE
 explicit unit_vector (size_type size, size_type index = 0):
 vector_container<self_type> (),
 size_ (size), index_ (index) {}
+
+ /// \brief Copy-constructor
 BOOST_UBLAS_INLINE
 unit_vector (const unit_vector &v):
 vector_container<self_type> (),
 size_ (v.size_), index_ (v.index_) {}

 // Accessors
+ //----------
+
+ /// \brief Return the size (dimension) of the vector
 BOOST_UBLAS_INLINE
 size_type size () const {
 return size_;
 }
+
+ /// \brief Return the order of the unit vector
 BOOST_UBLAS_INLINE
 size_type index () const {
 return index_;
 }

 // Resizing
+ // --------
+
+ /// \brief Resize the vector. The values are preserved by default (i.e. the index does not change)
+ /// \param size is the new size of the vector
 BOOST_UBLAS_INLINE
 void resize (size_type size, bool /*preserve*/ = true) {
 size_ = size;
 }

 // Element support
+ // ---------------
+
+ /// \brief Return a const pointer to the element of index i
 BOOST_UBLAS_INLINE
 const_pointer find_element (size_type i) const {
 if (i == index_)
@@ -1021,8 +1322,11 @@
 template<class T, class ALLOC>
 typename unit_vector<T, ALLOC>::const_value_type unit_vector<T, ALLOC>::one_ (1); // ISSUE: need 'one'-traits here

-
- // Scalar vector class
+ /// \brief A scalar (i.e. unique value) vector of type \c T and a given \c size
+ /// A scalar (i.e. unique value) vector of type \c T and a given \c size. This is a virtual vector in the sense that no memory is allocated
+ /// for storing the unique value more than once: it still acts like any other vector. However assigning a new value will change all the value at once.
+ /// vector into a normal vector. It must first be assigned to another normal vector by any suitable means. Its memory footprint is constant.
+ /// \tparam T type of the objects stored in the vector: it can be anything even if most of the time, scalar types will be used like \c double or \c int. Complex types can be used, or even classes like boost::interval.
 template<class T, class ALLOC>
 class scalar_vector:
 public vector_container<scalar_vector<T, ALLOC> > {
@@ -1258,8 +1562,11 @@
 value_type value_;
 };

-
+ // ------------------------
 // Array based vector class
+ // ------------------------
+
+ /// \brief A dense vector of values of type \c T with the given \c size. The data is stored as an ordinary C++ array \c T \c data_[M]
 template<class T, std::size_t N>
 class c_vector:
 public vector_container<c_vector<T, N> > {

Modified: trunk/boost/numeric/ublas/vector_proxy.hpp
==============================================================================
--- trunk/boost/numeric/ublas/vector_proxy.hpp (original)
+++ trunk/boost/numeric/ublas/vector_proxy.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -21,7 +21,15 @@

namespace boost { namespace numeric { namespace ublas {

- // Vector based range class
+ /** \brief A vector referencing a continuous subvector of elements of vector \c v containing all elements specified by \c range.
+ *
+ * A vector range can be used as a normal vector in any expression.
+ * If the specified range falls outside that of the index range of the vector, then
+ * the \c vector_range is not a well formed \i Vector \i Expression and access to an
+ * element outside of index range of the vector is \b undefined.
+ *
+ * \tparam V the type of vector referenced (for example \c vector<double>)
+ */
 template<class V>
 class vector_range:
 public vector_expression<vector_range<V> > {
@@ -476,13 +484,27 @@
 range_type r_;
 };

+ // ------------------
 // Simple Projections
+ // ------------------
+
+ /** \brief Return a \c vector_range on a specified vector, a start and stop index.
+ * Return a \c vector_range on a specified vector, a start and stop index. The resulting \c vector_range can be manipulated like a normal vector.
+ * If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 vector_range<V> subrange (V &data, typename V::size_type start, typename V::size_type stop) {
 typedef basic_range<typename V::size_type, typename V::difference_type> range_type;
 return vector_range<V> (data, range_type (start, stop));
 }
+
+ /** \brief Return a \c const \c vector_range on a specified vector, a start and stop index.
+ * Return a \c const \c vector_range on a specified vector, a start and stop index. The resulting \c const \c vector_range can be manipulated like a normal vector.
+ *If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 vector_range<const V> subrange (const V &data, typename V::size_type start, typename V::size_type stop) {
@@ -490,23 +512,49 @@
 return vector_range<const V> (data, range_type (start, stop));
 }

+ // -------------------
 // Generic Projections
+ // -------------------
+
+ /** \brief Return a \c const \c vector_range on a specified vector and \c range
+ * Return a \c const \c vector_range on a specified vector and \c range. The resulting \c vector_range can be manipulated like a normal vector.
+ * If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 vector_range<V> project (V &data, typename vector_range<V>::range_type const &r) {
 return vector_range<V> (data, r);
 }
+
+ /** \brief Return a \c vector_range on a specified vector and \c range
+ * Return a \c vector_range on a specified vector and \c range. The resulting \c vector_range can be manipulated like a normal vector.
+ * If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 const vector_range<const V> project (const V &data, typename vector_range<V>::range_type const &r) {
 // ISSUE was: return vector_range<V> (const_cast<V &> (data), r);
 return vector_range<const V> (data, r);
- }
+ }
+
+ /** \brief Return a \c const \c vector_range on a specified vector and const \c range
+ * Return a \c const \c vector_range on a specified vector and const \c range. The resulting \c vector_range can be manipulated like a normal vector.
+ * If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 vector_range<V> project (vector_range<V> &data, const typename vector_range<V>::range_type &r) {
 return data.project (r);
 }
+
+ /** \brief Return a \c vector_range on a specified vector and const \c range
+ * Return a \c vector_range on a specified vector and const \c range. The resulting \c vector_range can be manipulated like a normal vector.
+ * If the specified range falls outside that of of the index range of the vector, then the resulting \c vector_range is not a well formed
+ * Vector Expression and access to an element outside of index range of the vector is \b undefined.
+ */
 template<class V>
 BOOST_UBLAS_INLINE
 const vector_range<V> project (const vector_range<V> &data, const typename vector_range<V>::range_type &r) {
@@ -522,7 +570,20 @@
 : vector_temporary_traits< V > {} ;

- // Vector based slice class
+ /** \brief A vector referencing a non continuous subvector of elements of vector v containing all elements specified by \c slice.
+ *
+ * A vector slice can be used as a normal vector in any expression.
+ * If the specified slice falls outside that of the index slice of the vector, then
+ * the \c vector_slice is not a well formed \i Vector \i Expression and access to an
+ * element outside of index slice of the vector is \b undefined.
+ *
+ * A slice is a generalization of a range. In a range going from \f$a\f$ to \f$b\f$,
+ * all elements belong to the range. In a slice, a \i \f$step\f$ can be specified meaning to
+ * take one element over \f$step\f$ in the range specified from \f$a\f$ to \f$b\f$.
+ * Obviously, a slice with a \f$step\f$ of 1 is equivalent to a range.
+ *
+ * \tparam V the type of vector referenced (for example \c vector<double>)
+ */
 template<class V>
 class vector_slice:
 public vector_expression<vector_slice<V> > {
@@ -1046,6 +1107,26 @@
 // Vector based indirection class
 // Contributed by Toon Knapen.
 // Extended and optimized by Kresimir Fresl.
+
+ /** \brief A vector referencing a non continuous subvector of elements given another vector of indices.
+ *
+ * It is the most general version of any subvectors because it uses another vector of indices to reference
+ * the subvector.
+ *
+ * The vector of indices can be of any type with the restriction that its elements must be
+ * type-compatible with the size_type \c of the container. In practice, the following are good candidates:
+ * - \c boost::numeric::ublas::indirect_array<A> where \c A can be \c int, \c size_t, \c long, etc...
+ * - \c std::vector<A> where \c A can \c int, \c size_t, \c long, etc...
+ * - \c boost::numeric::ublas::vector<int> can work too (\c int can be replaced by another integer type)
+ * - etc...
+ *
+ * An indirect vector can be used as a normal vector in any expression. If the specified indirect vector
+ * falls outside that of the indices of the vector, then the \c vector_indirect is not a well formed
+ * \i Vector \i Expression and access to an element outside of indices of the vector is \b undefined.
+ *
+ * \tparam V the type of vector referenced (for example \c vector<double>)
+ * \tparam IA the type of index vector. Default is \c ublas::indirect_array<>
+ */
 template<class V, class IA>
 class vector_indirect:
 public vector_expression<vector_indirect<V, IA> > {

Modified: trunk/boost/numeric/ublas/vector_sparse.hpp
==============================================================================
--- trunk/boost/numeric/ublas/vector_sparse.hpp (original)
+++ trunk/boost/numeric/ublas/vector_sparse.hpp 2010-07-04 17:43:41 EDT (Sun, 04 Jul 2010)
@@ -260,7 +260,22 @@
#endif

- // Index map based sparse vector class
+ /** \brief Index map based sparse vector
+ *
+ * A sparse vector of values of type T of variable size. The sparse storage type A can be
+ * \c std::map<size_t, T> or \c map_array<size_t, T>. This means that only non-zero elements
+ * are effectively stored.
+ *
+ * For a \f$n\f$-dimensional sparse vector, and 0 <= i < n the non-zero elements \f$v_i\f$
+ * are mapped to consecutive elements of the associative container, i.e. for elements
+ * \f$k = v_{i_1}\f$ and \f$k + 1 = v_{i_2}\f$ of the container, holds \f$i_1 < i_2\f$.
+ *
+ * Supported parameters for the adapted array are \c map_array<std::size_t, T> and
+ * \c map_std<std::size_t, T>. The latter is equivalent to \c std::map<std::size_t, T>.
+ *
+ * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+ * \tparam A the type of Storage array
+ */
 template<class T, class A>
 class mapped_vector:
 public vector_container<mapped_vector<T, A> > {
@@ -755,8 +770,29 @@
 const typename mapped_vector<T, A>::value_type mapped_vector<T, A>::zero_ = value_type/*zero*/();

- // Compressed array based sparse vector class
 // Thanks to Kresimir Fresl for extending this to cover different index bases.
+
+ /** \brief Compressed array based sparse vector
+ *
+ * a sparse vector of values of type T of variable size. The non zero values are stored as
+ * two seperate arrays: an index array and a value array. The index array is always sorted
+ * and there is at most one entry for each index. Inserting an element can be time consuming.
+ * If the vector contains a few zero entries, then it is better to have a normal vector.
+ * If the vector has a very high dimension with a few non-zero values, then this vector is
+ * very memory efficient (at the cost of a few more computations).
+ *
+ * For a \f$n\f$-dimensional compressed vector and \f$0 \leq i < n\f$ the non-zero elements
+ * \f$v_i\f$ are mapped to consecutive elements of the index and value container, i.e. for
+ * elements \f$k = v_{i_1}\f$ and \f$k + 1 = v_{i_2}\f$ of these containers holds \f$i_1 < i_2\f$.
+ *
+ * Supported parameters for the adapted array (indices and values) are \c unbounded_array<> ,
+ * \c bounded_array<> and \c std::vector<>.
+ *
+ * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+ * \tparam IB the index base of the compressed vector. Default is 0. Other supported value is 1
+ * \tparam IA the type of adapted array for indices. Default is \c unbounded_array<std::size_t>
+ * \tparam TA the type of adapted array for values. Default is unbounded_array<T>
+ */
 template<class T, std::size_t IB, class IA, class TA>
 class compressed_vector:
 public vector_container<compressed_vector<T, IB, IA, TA> > {
@@ -1374,9 +1410,29 @@
 template<class T, std::size_t IB, class IA, class TA>
 const typename compressed_vector<T, IB, IA, TA>::value_type compressed_vector<T, IB, IA, TA>::zero_ = value_type/*zero*/();

-
- // Coordimate array based sparse vector class
 // Thanks to Kresimir Fresl for extending this to cover different index bases.
+
+ /** \brief Coordimate array based sparse vector
+ *
+ * a sparse vector of values of type \c T of variable size. The non zero values are stored
+ * as two seperate arrays: an index array and a value array. The arrays may be out of order
+ * with multiple entries for each vector element. If there are multiple values for the same
+ * index the sum of these values is the real value. It is way more efficient for inserting values
+ * than a \c compressed_vector but less memory efficient. Also linearly parsing a vector can
+ * be longer in specific cases than a \c compressed_vector.
+ *
+ * For a n-dimensional sorted coordinate vector and \f$ 0 \leq i < n\f$ the non-zero elements
+ * \f$v_i\f$ are mapped to consecutive elements of the index and value container, i.e. for
+ * elements \f$k = v_{i_1}\f$ and \f$k + 1 = v_{i_2}\f$ of these containers holds \f$i_1 < i_2\f$.
+ *
+ * Supported parameters for the adapted array (indices and values) are \c unbounded_array<> ,
+ * \c bounded_array<> and \c std::vector<>.
+ *
+ * \tparam T the type of object stored in the vector (like double, float, complex, etc...)
+ * \tparam IB the index base of the compressed vector. Default is 0. Other supported value is 1
+ * \tparam IA the type of adapted array for indices. Default is \c unbounded_array<std::size_t>
+ * \tparam TA the type of adapted array for values. Default is unbounded_array<T>
+ */
 template<class T, std::size_t IB, class IA, class TA>
 class coordinate_vector:
 public vector_container<coordinate_vector<T, IB, IA, TA> > {

Next message: nielsdekker_at_[hidden]: "[Boost-commit] svn:boost r63637 - branches/release/boost/utility"
Previous message: barend.gehrels_at_[hidden]: "[Boost-commit] svn:boost r63635 - sandbox/geometry/libs/geometry/test/strategies"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk