Add doxygen documentation.

Add doxygen documentation.
Doxygen is great.  Forget grdoc.  Forget you even ever heard its name.

darcs-hash:20030803142621-07bb3-e18d0b14080698cd6ddbe94deb678ce0a29fd339.gz

2 files changed, 134 insertions, 31 deletions

diff --git a/Carpet/CarpetLib/src/instantiate b/Carpet/CarpetLib/src/instantiate
index 4199e0e91..a036e4872 100644
--- a/Carpet/CarpetLib/src/instantiate
+++ b/Carpet/CarpetLib/src/instantiate
@@ -1,7 +1,7 @@
 // Instantiate templates for all available types    -*-C++-*-
 // (C) 2001 Erik Schnetter <schnetter@uni-tuebingen.de>
 
-// $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetLib/src/instantiate,v 1.6 2003/01/07 22:17:32 schnetter Exp $
+// $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetLib/src/instantiate,v 1.7 2003/08/03 16:26:21 schnetter Exp $
 
 // Usage:
 // Define the macro INSTANTIATE(T) to instantiate for the type T,
@@ -56,7 +56,7 @@
 #  define CARPET_COMPLEX32
 #endif
 
-#if !defined(CARPET_BYTE) && !defined(CARPET_INT1) && !defined(CARPET_INT2) && !defined(CARPET_INT4) && !defined(CARPET_INT8) && !defined(CARPET_REAL4) && !defined(CARPET_REAL8) && !defined(CARPET_REAL16) && !defined(CARPET_COMPLEX8) && !defined(CARPET_COMPLEX16) && !defined(CARPET_COMPLEX32)
+#if !defined(CARPET_BYTE) && !defined(CARPET_INT) && !defined(CARPET_INT1) && !defined(CARPET_INT2) && !defined(CARPET_INT4) && !defined(CARPET_INT8) && !defined(CARPET_REAL) && !defined(CARPET_REAL4) && !defined(CARPET_REAL8) && !defined(CARPET_REAL16) && !defined(CARPET_COMPLEX) && !defined(CARPET_COMPLEX8) && !defined(CARPET_COMPLEX16) && !defined(CARPET_COMPLEX32)
 // Assume the user just wants INT and REAL
 #  undef CARPET_INT
 #  define CARPET_INT
diff --git a/Carpet/CarpetLib/src/vect.hh b/Carpet/CarpetLib/src/vect.hh
index 4b615f12e..a618196c5 100644
--- a/Carpet/CarpetLib/src/vect.hh
+++ b/Carpet/CarpetLib/src/vect.hh
@@ -1,4 +1,4 @@
-// $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetLib/src/vect.hh,v 1.16 2003/07/17 15:40:28 schnetter Exp $
+// $Header: /home/eschnett/C/carpet/Carpet/Carpet/CarpetLib/src/vect.hh,v 1.17 2003/08/03 16:26:21 schnetter Exp $
 
 #ifndef VECT_HH
 #define VECT_HH
@@ -23,98 +23,122 @@ ostream& operator<< (ostream& os, const vect<T,D>& a);
 
 
 
-// Vect class
+/**
+ * A short vector with a size that is specified at compile time.
+ */
 template<class T, int D>
 class vect {
   
   // Fields
+  
+  /** Vector elements.  */
   T elt[D];
   
 public:
   
   // Constructors
+  
+  /** Explicit empty constructor.  */
   explicit vect () { }
   
+  /** Copy constructor.  */
   vect (const vect& a) {
     for (int d=0; d<D; ++d) elt[d]=a.elt[d];
   }
   
-  // this constructor might be confusing, but it is so convenient
+  /** Constructor from a single element.  This constructor might be
+      confusing, but it is very convenient.  */
   vect (const T x) {
     for (int d=0; d<D; ++d) elt[d]=x;
   }
   
+  /** Constructor for 2-element vectors from 2 elements.  */
   vect (const T x, const T y) {
     assert (D==2);
     elt[0]=x; elt[1]=y;
   }
   
+  /** Constructor for 3-element vectors from 4 elements.  */
   vect (const T x, const T y, const T z) {
     assert (D==3);
     elt[0]=x; elt[1]=y; elt[2]=z;
   }
   
+  /** Constructor for 4-element vectors from 4 elements.  */
   vect (const T x, const T y, const T z, const T t) {
     assert (D==4);
     elt[0]=x; elt[1]=y; elt[2]=z; elt[3]=t;
   }
   
+  /** Constructor from a pointer, i.e.\ a C array.  */
   vect (const T* const x) {
     for (int d=0; d<D; ++d) elt[d]=x[d];
   }
   
+  /** Constructor from a vector with a different type.  */
   template<class S>
   explicit vect (const vect<S,D>& a) {
     for (int d=0; d<D; ++d) elt[d]=(T)a[d];
   }
   
+  /** Create a new 0-element vector with a specific type.  */
   static vect make () {
     assert (D==0);
     return vect();
   }
   
+  /** Create a new 1-element vector with a specific type.  */
   static vect make (const T x) {
     assert (D==1);
     return vect(x);
   }
   
+  /** Create a new 2-element vector with a specific type.  */
   static vect make (const T x, const T y) {
     assert (D==2);
     return vect(x, y);
   }
   
+  /** Create a new 3-element vector with a specific type.  */
   static vect make (const T x, const T y, const T z) {
     assert (D==3);
     return vect(x, y, z);
   }
   
+  /** Create a new 4-element vector with a specific type.  */
   static vect make (const T x, const T y, const T z, const T t) {
     assert (D==4);
     return vect(x, y, z, t);
   }
   
+  /** Treat a pointer as a reference to a vector.  */
   static vect& ref (T* const x) {
     return *(vect*)x;
   }
   
+  /** Create a vector with one element set to 1 and all other elements
+      set to zero.  */
   static vect dir (const int d) {
     vect r=(T)0;
     r[d]=1;
     return r;
   }
   
+  /** Create a vector with e[i] = i.  */
   static vect seq () {
     vect r;
     for (int d=0; d<D; ++d) r[d]=d;
     return r;
   }
   
+  /** Create a vector with e[i] = n + i.  */
   static vect seq (const int n) {
     vect r;
     for (int d=0; d<D; ++d) r[d]=n+d;
     return r;
   }
   
+  /** Create a vector with e[i] = n + s * i.  */
   static vect seq (const int n, const int s) {
     vect r;
     for (int d=0; d<D; ++d) r[d]=n+s*d;
@@ -122,17 +146,22 @@ public:
   }
   
   // Accessors
+  
+  /** Return a non-writable element of a vector.  */
   // Don't return a reference; *this might be a temporary
   const T operator[] (const int d) const {
     assert(d>=0 && d<D);
     return elt[d];
   }
   
+  /** Return a writable element of a vector as reference.  */
   T& operator[] (const int d) {
     assert(d>=0 && d<D);
     return elt[d];
   }
   
+  /** Return a combination of the vector elements e[a[i]].  The
+      element combination is selected by another vector.  */
   template<class TT, int DD>
   vect<T,DD> operator[] (const vect<TT,DD>& a) const {
     vect<T,DD> r;
@@ -223,6 +252,8 @@ public:
   }
   
   // Non-modifying operators
+  
+  /** Return a new vector where one element has been replaced.  */
   vect replace (const int d, const T x) const {
     assert (d>=0 && d<D);
     vect r;
@@ -410,6 +441,9 @@ public:
     return r;
   }
   
+  /** This corresponds to the ?: operator.  Return a vector with the
+      elements set to either a[i] or b[i], depending on whether
+      (*this)[i] is true or not.  */
   template<class TT>
   vect<TT,D> ifthen (const vect<TT,D>& a, const vect<TT,D>& b) const {
     vect<TT,D> r;
@@ -432,25 +466,47 @@ public:
 #endif
   
   // Higher order functions
-  vect map (T (* const func)(T x)) const {
-    vect r;
+  
+  /** Return a new vector where the function func() has been applied
+      to all elements.  */
+  template<class U>
+  vect<U,D> map (U (* const func)(T x)) const {
+    vect<U,D> r;
     for (int d=0; d<D; ++d) r[d] = func(elt[d]);
     return r;
   }
   
-  template<class S>
-  vect zip (T (* const func)(T x, S y), const vect<S,D>& a) const {
+  /** Return a new vector where the function func() has been used
+      element-wise to combine *this and a.  */
+  template<class S, class U>
+  vect<U,D> zip (U (* const func)(T x, S y), const vect<S,D>& a) const {
     vect r;
     for (int d=0; d<D; ++d) r[d] = func(elt[d], a[d]);
     return r;
   }
   
-  T fold (T (* const func)(T val, T x), T val) const {
+  /** Return a scalar where the function func() has been used to
+      reduce the vector, starting with the scalar value val.  */
+  template<class U>
+  U fold (U (* const func)(U val, T x), U val) const {
     for (int d=0; d<D; ++d) val = func(val, elt[d]);
     return val;
   }
   
-  vect scan0 (T (* const func)(T val, T x), T val) const {
+  /** Return a scalar where the function func() has been used to
+      reduce the vector, starting with element 0.  */
+  template<class U>
+  U fold1 (U (* const func)(U val, T x)) const {
+    assert (D>=1);
+    U val = elt[0];
+    for (int d=1; d<D; ++d) val = func(val, elt[d]);
+    return val;
+  }
+  
+  /** Return a vector where the function func() has been used to scan
+      the vector, starting with the scalar value val.  */
+  template<class U>
+  vect<U,D> scan0 (U (* const func)(U val, T x), U val) const {
     vect r;
     for (int d=0; d<D; ++d) {
       r[d] = val;
@@ -459,9 +515,14 @@ public:
     return r;
   }
   
-  vect scan1 (T (* const func)(T val, T x), T val) const {
+  /** Return a vector where the function func() has been used to scan
+      the vector, starting with element 0.  */
+  template<class U>
+  vect<U,D> scan1 (U (* const func)(U val, T x)) const {
     vect r;
-    for (int d=0; d<D; ++d) {
+    assert (D>=1);
+    U val = elt[0];
+    for (int d=1; d<D; ++d) {
       val = func(val, elt[d]);
       r[d] = val;
     }
@@ -476,6 +537,8 @@ public:
 
 
 // Operators
+
+/** Return the element-wise absolute value.  */
 template<class T,int D>
 inline vect<T,D> abs (const vect<T,D>& a) {
   vect<T,D> r;
@@ -483,6 +546,7 @@ inline vect<T,D> abs (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the element-wise maximum of two vectors.  */
 template<class T,int D>
 inline vect<T,D> max (const vect<T,D>& a, const vect<T,D>& b) {
   vect<T,D> r;
@@ -490,6 +554,7 @@ inline vect<T,D> max (const vect<T,D>& a, const vect<T,D>& b) {
   return r;
 }
 
+/** Return the element-wise minimum of two vectors.  */
 template<class T,int D>
 inline vect<T,D> min (const vect<T,D>& a, const vect<T,D>& b) {
   vect<T,D> r;
@@ -500,6 +565,8 @@ inline vect<T,D> min (const vect<T,D>& a, const vect<T,D>& b) {
 
 
 // Reduction operators
+
+/** Return true iff any of the elements are true (boolean sum).  */
 template<int D>
 inline bool any (const vect<bool,D>& a) {
   bool r(false);
@@ -507,6 +574,7 @@ inline bool any (const vect<bool,D>& a) {
   return r;
 }
 
+/** Return true iff all of the elements are true (boolean product).  */
 template<int D>
 inline bool all (const vect<bool,D>& a) {
   bool r(true);
@@ -514,11 +582,13 @@ inline bool all (const vect<bool,D>& a) {
   return r;
 }
 
+/** Count the number of elements in the vector.  */
 template<class T,int D>
 inline int count (const vect<T,D>& a) {
   return D;
 }
 
+/** Return the dot product of two vectors.  */
 template<class T,int D>
 inline T dot (const vect<T,D>& a, const vect<T,D>& b) {
   T r(0);
@@ -526,11 +596,13 @@ inline T dot (const vect<T,D>& a, const vect<T,D>& b) {
   return r;
 }
 
+/** Return the Euklidean length.  */
 template<class T,int D>
 inline T hypot (const vect<T,D>& a) {
   return sqrt(dot(a,a));
 }
 
+/** Return the maximum element.  */
 template<class T,int D>
 inline T maxval (const vect<T,D>& a) {
   assert (D>0);
@@ -539,6 +611,7 @@ inline T maxval (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the minimum element.  */
 template<class T,int D>
 inline T minval (const vect<T,D>& a) {
   assert (D>0);
@@ -547,6 +620,7 @@ inline T minval (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the index of the first maximum element.  */
 template<class T,int D>
 inline int maxloc (const vect<T,D>& a) {
   assert (D>0);
@@ -555,6 +629,7 @@ inline int maxloc (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the index of the first minimum element.  */
 template<class T,int D>
 inline int minloc (const vect<T,D>& a) {
   assert (D>0);
@@ -563,6 +638,7 @@ inline int minloc (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the product of the elements.  */
 template<class T,int D>
 inline T prod (const vect<T,D>& a) {
   T r(1);
@@ -570,11 +646,13 @@ inline T prod (const vect<T,D>& a) {
   return r;
 }
 
+/** Return the size (number of elements) of the vector.  */
 template<class T,int D>
 inline int size (const vect<T,D>& a) {
   return D;
 }
 
+/** Return the sum of the elements.  */
 template<class T,int D>
 inline T sum (const vect<T,D>& a) {
   T r(0);
@@ -583,35 +661,54 @@ inline T sum (const vect<T,D>& a) {
 }
 
 // Higher order functions
-template<class T,class TT,int D>
-inline vect<TT,D> map (TT (* const func)(T x), const vect<T,D>& a) {
-  vect<TT,D> r;
+
+/** Return a new vector where the function func() has been applied to
+    all elements.  */
+template<class T, class U, int D>
+inline vect<U,D> map (U (* const func)(T x), const vect<T,D>& a) {
+  vect<U,D> r;
   for (int d=0; d<D; ++d) r[d] = func(a[d]);
   return r;
 }
   
-template<class T1,class T2,class TT,int D>
-inline vect<TT,D> zip (TT (* const func)(T1 x, T2 y),
-		       const vect<T1,D>& a, const vect<T2,D>& b)
+/** Return a new vector where the function func() has been used
+    element-wise to combine a and b.  */
+template<class S, class T, class U, int D>
+inline vect<U,D> zip (U (* const func)(S x, T y),
+                      const vect<S,D>& a, const vect<T,D>& b)
 {
-  vect<TT,D> r;
+  vect<U,D> r;
   for (int d=0; d<D; ++d) r[d] = func(a[d], b[d]);
   return r;
 }
 
-template<class T,class TT,int D>
-inline vect<TT,D> fold (TT (* const func)(TT val, T x), TT val,
-			const vect<T,D>& a)
+/** Return a scalar where the function func() has been used to reduce
+    the vector a, starting with the scalar value val.  */
+template<class T, class U, int D>
+inline U fold (U (* const func)(U val, T x), U val, const vect<T,D>& a)
 {
   for (int d=0; d<D; ++d) val = func(val, a[d]);
   return val;
 }
+  
+/** Return a scalar where the function func() has been used to reduce
+    the vector a, starting with element 0.  */
+template<class T, class U, int D>
+inline U fold1 (U (* const func)(U val, T x))
+{
+  assert (D>=1);
+  U val = elt[0];
+  for (int d=1; d<D; ++d) val = func(val, elt[d]);
+  return val;
+}
 
-template<class T,class TT,int D>
-inline vect<TT,D> scan0 (TT (* const func)(TT val, T x), TT val,
-			 const vect<T,D>& a)
+/** Return a vector where the function func() has been used to scan
+    the vector a, starting with the scalar value val.  */
+template<class T, class U, int D>
+inline vect<U,D> scan0 (U (* const func)(U val, T x), U val,
+                        const vect<T,D>& a)
 {
-  vect<TT,D> r;
+  vect<U,D> r;
   for (int d=0; d<D; ++d) {
     r[d] = val;
     val = func(val, a[d]);
@@ -619,11 +716,13 @@ inline vect<TT,D> scan0 (TT (* const func)(TT val, T x), TT val,
   return r;
 }
 
-template<class T,class TT,int D>
-inline vect<TT,D> scan1 (TT (* const func)(TT val, T x), TT val,
-			 const vect<T,D>& a)
+/** Return a vector where the function func() has been used to scan
+    the vector a, starting with element 0.  */
+template<class T, class U, int D>
+inline vect<U,D> scan1 (U (* const func)(U val, T x), U val,
+                        const vect<T,D>& a)
 {
-  vect<TT,D> r;
+  vect<U,D> r;
   for (int d=0; d<D; ++d) {
     val = func(val, a[d]);
     r[d] = val;
@@ -634,6 +733,8 @@ inline vect<TT,D> scan1 (TT (* const func)(TT val, T x), TT val,
 
 
 // Input
+
+/** Read a formatted vector from a stream.  */
 template<class T,int D>
 inline istream& operator>> (istream& is, vect<T,D>& a) {
   a.input(is);
@@ -643,6 +744,8 @@ inline istream& operator>> (istream& is, vect<T,D>& a) {
 
 
 // Output
+
+/** Write a vector formatted to a stream.  */
 template<class T,int D>
 inline ostream& operator<< (ostream& os, const vect<T,D>& a) {
   a.output(os);