gmsh doc: first try -- Doxyfile and fullVector

Numeric/fullMatrix.h

@@ -13,6 +13,30 @@
 
 template <class scalar> class fullMatrix;
 
+/**
+   @class fullVector
+   @brief Vector of scalar
+
+   This class represents a vector of scalar.@n
+   Scalars can be real or complex, with simple or double precision.
+
+   The first index of a fullVector is @c 0.
+
+   fullVector%s can own their scalars,
+   or just be an access point to an other fullVector.@n
+   Such a fullVector is called a proxy.
+
+   @see fullVector::setAsProxy(const fullVector&, int, int)
+*/
+
+/**
+   @class fullMatrix
+   @brief Matrix of scalar
+
+   This class represents a matrix of scalar.@n
+   Scalars can be real or complex, with simple or double precision.
+*/
+
 // An abstract interface for vectors of scalar
 template <class scalar>
 class fullVector
@@ -25,35 +49,87 @@ class fullVector
 
  public:
   // constructor and destructor
+  /**
+     Instantiates a zero size fullVector.
+  */
   fullVector(void) : _r(0),_data(0),_own_data(1) {}
+
+  /**
+     @param r A positive integer.
+
+     Instantiates a fullVector of size r filled with zeros.
+  */
   fullVector(int r) : _r(r),_own_data(1)
   {
     _data = new scalar[_r];
     setAll(scalar(0.));
   }
 
+  /**
+     @param original A scalar pointer;
+     @param r A positive integer.
+
+     Instantiates a proxy fullVector given by:
+     [original[0], original[1], ..., original[r - 1]].
+  */
   fullVector(scalar *original, int r)
   {
     _r = r;
     _own_data = false;
     _data = original;
   }
+
+  /**
+     @param other A fullVector.
+
+     Instantiates a fullVector, which is a copy (and not a proxy) of other.
+  */
   fullVector(const fullVector<scalar> &other) : _r(other._r),_own_data(1)
   {
     _data = new scalar[_r];
     for(int i = 0; i < _r; ++i) _data[i] = other._data[i];
   }
+
+  /**
+     Deletes this fullVector.
+  */
   ~fullVector()
   {
     if(_own_data && _data) delete [] _data;
   }
 
   // get information (size, value)
+  /**
+     @return Returns the size of this fullVector
+  */
   inline int size()                  const { return _r; }
+
+  /**
+     @return Returns a const pointer to this fullVector data.@n
+     This pointer will point to the following memory segment:
+     [(*this)(0), (*this)(1), ..., (*this)(this->size() - 1)].
+  */
   inline const scalar * getDataPtr() const { return _data; }
+
+  /**
+     @param i A vector index between 0 and size() - 1.
+     @returns Returns the ith scalar of this fullVector.
+  */
   inline scalar operator () (int i)  const { return _data[i]; }
+
+  /**
+     @param i A vector index between 0 and size() - 1.
+     @returns Returns a reference to the ith scalar of this fullVector.
+  */
   inline scalar & operator () (int i)      { return _data[i]; }
+
   // copy
+  /**
+     @param other A fullVector.
+
+     The right hand side fullVector will become a copy of other,
+     and will loose its previous data.
+  */
   fullVector<scalar>& operator= (const fullVector<scalar> &other)
   {
     if (this != &other) {
@@ -66,7 +142,14 @@ class fullVector
     }
     return *this;
   }
+
   // set
+  /**
+     @param r A vector index between 0 and size() - 1;
+     @param v A scalar.
+
+     The rth value of this fullVector is set to v.
+  */
   inline void set(int r, scalar v){
     #ifdef _DEBUG
     if (r >= _r || r < 0)
@@ -77,12 +160,34 @@ class fullVector
   }
 
   // operations
+  /**
+     @return Returns the @f$ L^2 @f$ norm of this fullVector.
+  */
   inline scalar norm() const
   {
     scalar n = 0.;
     for(int i = 0; i < _r; ++i) n += _data[i] * _data[i];
     return sqrt(n);
   }
+
+  /**
+     @param r A positive integer;
+     @param resetValue A boolean (with default value equals to true).
+
+     Resizes this fullVector to r. Previous data may be damaged.@n
+     If resetValue is true, the fullVector data are set to zero.@n
+     If this fullVector was a proxy, it now owns its data.
+
+     @return Returns:
+     @li true if the previous data are damaged;
+     @li false if not (except if resetValue is true).
+
+     @warning
+     Nicolas: I'm not sure if this is exactly what resize does !
+
+     @todo
+     Check doc of fullVector::resize()
+  */
   bool resize(int r, bool resetValue = true)
   {
     if (_r < r || !_own_data) {
@@ -99,6 +204,17 @@ class fullVector
       setAll(scalar(0.));
     return false;
   }
+
+  /**
+     @param original A fullVector;
+     @param r_start A valid index of original;
+     @param r A number between 0 and original.size() - r_start.
+
+     This fullVector becomes a proxy of original, that is:
+     [original(r_start), ..., original(r_start + r - 1)].
+
+     Previous data are lost.
+  */
   void setAsProxy(const fullVector<scalar> &original, int r_start, int r)
   {
     if(_own_data && _data) delete [] _data;
@@ -106,6 +222,16 @@ class fullVector
     _r = r;
     _data = original._data + r_start;
   }
+
+  /**
+     @param original A fullMatrix;
+     @param c A valid column index of original.
+
+     This fullVector becomes a proxy of original cth row, that is:
+     [original(0, c), ..., original(original.size1() - 1, c)].
+
+     Previous data are lost.
+  */
   void setAsProxy(const fullMatrix<scalar> &original, int c)
   {
     if(_own_data && _data) delete [] _data;
@@ -113,6 +239,12 @@ class fullVector
     _r = original._r;
     _data = original._data + c * _r;
   }
+
+  /**
+     @param s A scalar.
+
+     Multiplies all the data of this fullVector by s.
+  */
   inline void scale(const scalar s)
   {
     if(s == scalar(0.))
@@ -122,20 +254,60 @@ class fullVector
     else
       for(int i = 0; i < _r; ++i) _data[i] *= s;
   }
+
+  /**
+     @param m A scalar.
+
+     Sets all the data of this fullVector to m.
+  */
   inline void setAll(const scalar &m)
   {
     for(int i = 0; i < _r; i++) set(i,m);
   }
+
+  /**
+     @param m A fullVector.
+
+     If:
+     @li @f$ v @f$ is this fullVector;
+     @li @f$ N @f$ is equal to this fullVector size,
+
+     then:
+     @f$ v(i) = m(i) \qquad \forall{} i \in \{0, \dots, N - 1\} @f$.
+
+     m.size() must be greater or equal to @f$ N @f$.
+  */
   inline void setAll(const fullVector<scalar> &m)
   {
     for(int i = 0; i < _r; i++) _data[i] = m._data[i];
   }
+
+  /**
+     @param other A fullVector.
+
+     @return Returns the scalar product of this fullVector with the other.
+  */
   inline scalar operator *(const fullVector<scalar> &other)
   {
     scalar s = 0.;
     for(int i = 0; i < _r; ++i) s += _data[i] * other._data[i];
     return s;
   }
+
+  /**
+     @param x A fullVector;
+     @param alpha A scalar (by default set to one).
+
+     If:
+     @li @f$ v @f$ is this fullVector;
+     @li @f$ N @f$ is equal to this fullVector size,
+
+     then:
+     @f$ v(i) = v(i) + alpha \times{} x(i) \qquad
+     \forall{} i \in \{0, \dots, N - 1\} @f$.
+
+     x.size() must be greater or equal to @f$ N @f$.
+  */
   void axpy(const fullVector<scalar> &x, scalar alpha=1.)
 #if !defined(HAVE_BLAS)
   {
@@ -143,12 +315,34 @@ class fullVector
   }
 #endif
   ;
+
+  /**
+     @param x A fullVector.
+
+     If:
+     @li @f$ v @f$ is this fullVector;
+     @li @f$ N @f$ is equal to this fullVector size,
+
+     then:
+     @f$ v(i) = v(i) \times{} x(i) \qquad
+     \forall{} i \in \{0, \dots, N - 1\} @f$.
+
+     x.size() must be greater or equal to @f$ N @f$.
+  */
   void multTByT(const fullVector<scalar> &x)
   {
     for (int i = 0; i < _r; i++) _data[i] *= x._data[i];
   }
 
   // printing and file treatment
+  /**
+     @param name A string in @c C style (set by default to "").
+
+     Prints on the standard output a string describing
+     this fullVector.
+
+     This string starts by name.
+  */
   void print(const char *name="") const
   {
     printf("double %s[%d]=\n", name,size());
@@ -158,10 +352,26 @@ class fullVector
     }
     printf("};\n");
   }
+
+  /**
+     @param f A pointer to a FILE stream.
+
+     Writes a binary representation of this fullVector
+     into f.
+  */
   void binarySave (FILE *f) const
   {
     fwrite (_data, sizeof(scalar), _r, f);
   }
+
+  /**
+     @param f A pointer to a FILE stream containing a fullVector.
+
+     Loads a binary representation, of the fullVector in f,
+     into this fullVector.
+
+     @see fullVector::binarySave
+  */
   void binaryLoad (FILE *f)
   {
     if(fread (_data, sizeof(scalar), _r, f) != (size_t)_r) return;