[Boost-commit] svn:boost r63469 - branches/ublas-doxygen

Subject: [Boost-commit] svn:boost r63469 - branches/ublas-doxygen
From: david.bellot_at_[hidden]
Date: 2010-07-02 14:51:25

Author: david.bellot
Date: 2010-07-01 03:01:18 EDT (Thu, 01 Jul 2010)
New Revision: 63469
URL: http://svn.boost.org/trac/boost/changeset/63469

Log:
more doc exception
fixed little things in matrix
doc for hermitian matrix

Text files modified: 
   branches/ublas-doxygen/exception.hpp |    11 ++++++++++-                             
   branches/ublas-doxygen/fwd.hpp       |     6 ++++--                                  
   branches/ublas-doxygen/hermitian.hpp |    39 +++++++++++++++++++++------------------ 
   branches/ublas-doxygen/io.hpp        |     5 +++--                                   
   branches/ublas-doxygen/matrix.hpp    |     5 ++++-                                   
   5 files changed, 42 insertions(+), 24 deletions(-)

Modified: branches/ublas-doxygen/exception.hpp
==============================================================================
--- branches/ublas-doxygen/exception.hpp	(original)
+++ branches/ublas-doxygen/exception.hpp	2010-07-01 03:01:18 EDT (Thu, 01 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.
@@ -68,6 +73,8 @@
 #endif
     };
 
+    /** \brief Exceptions raised when ...
+     */
     struct external_logic
 #if ! defined (BOOST_NO_EXCEPTIONS) && ! defined (BOOST_UBLAS_NO_EXCEPTIONS)
         // Inherit from standard exceptions as requested during review.
@@ -113,6 +120,8 @@
 #endif
     };
 
+    /**
+     */
     struct bad_size
 #if ! defined (BOOST_NO_EXCEPTIONS) && ! defined (BOOST_UBLAS_NO_EXCEPTIONS)
         // Inherit from standard exceptions as requested during review.

Modified: branches/ublas-doxygen/fwd.hpp
==============================================================================
--- branches/ublas-doxygen/fwd.hpp	(original)
+++ branches/ublas-doxygen/fwd.hpp	2010-07-01 03:01:18 EDT (Thu, 01 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 This file is essentially used to forward declare main types */
+
 #ifndef BOOST_UBLAS_FWD_H
 #define BOOST_UBLAS_FWD_H
 

Modified: branches/ublas-doxygen/hermitian.hpp
==============================================================================
--- branches/ublas-doxygen/hermitian.hpp	(original)
+++ branches/ublas-doxygen/hermitian.hpp	2010-07-01 03:01:18 EDT (Thu, 01 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,22 +222,18 @@
     };
 
 #endif
-
-    // ----------------------------------
-    // Array based hermitian matrix class
-    // ----------------------------------
-    /**
-     * \brief A hermitian matrix of values of type \c T. Orientation can be specified, otherwise a row major and unbounded array are used.
+    /** \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} is mapped to the \f$(i x n + j)\f$-th element of the container for row major orientation 
+     * or the \f$(i + j x 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$.
      *
-     * A hermitian matrix of values of type \c T. 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. 
-     * Only the given triangular matrix is stored and the storage of hermitian matrices is packed.
-     * 
-     * 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} is mapped 
-     * to the \f$(i x n + j)\f$-th element of the container for row major orientation or the \f$(i + j x 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 and properties.
+     * See http://en.wikipedia.org/wiki/Hermitian_matrix for mor 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
@@ -1147,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$(mxn)\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: branches/ublas-doxygen/io.hpp
==============================================================================
--- branches/ublas-doxygen/io.hpp	(original)
+++ branches/ublas-doxygen/io.hpp	2010-07-01 03:01:18 EDT (Thu, 01 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,7 @@
 
 namespace boost { namespace numeric { namespace ublas {
 
+    /** \brief Output operator*/
     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,

Modified: branches/ublas-doxygen/matrix.hpp
==============================================================================
--- branches/ublas-doxygen/matrix.hpp	(original)
+++ branches/ublas-doxygen/matrix.hpp	2010-07-01 03:01:18 EDT (Thu, 01 Jul 2010)
@@ -32,7 +32,10 @@
          * A common practice is to bring this namespace into the current scope with
          * \code using namespace boost::numeric::ublas; \endcode.
          *
-	 * One has to be cautious when doing that and using STL vector<> at the same time because of the name conflict.
+	 * 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 {