first go at commenting

Also there were some interesting macro problems in FixedPoint which
should be resolved now.

Author: hv15

src/auxiliary/Benchmarking.sac

@@ -1,14 +1,8 @@
-/* Interface module
- * 
- * void start( Interval& interval);
- * void end( Interval& interval);
- * void benchThis();
- * void printResult( Interval& interval);
- * void benchThis();
- * Interval getInterval( string interval_name, int interval_number);
- * Interval getInterval( int interval_number);
- * Interval getInterval( int interval_number);
- * void destroyInterval( Interval interval);
+/**
+ * @file
+ * @defgroup bench Benchmarking Interface
+ *
+ * @{
  */
 
 module Benchmarking;
@@ -23,3 +17,5 @@ import C99Benchmarking: all;
 #ifdef SAC_BACKEND_MUTC
 import MutcBenchmarking: all;
 #endif /* SAC_BACKEND_MUTC */
+
+/** @} */

src/auxiliary/C99Benchmarking.sac

@@ -1,16 +1,20 @@
-/* C99 Benchmarking Module 
+/**
+ * @file
+ * @defgroup bench99 C99 Benchmarking
  *
  * Measures time Intervals in an arbitrary time unit as doubles.
  *
  * Use getInterval to construct a benchmarking interval object and start and
  * end to measure each interval. Take care when start and stop are evaluated
- * since this will affect the windows that is measured. The function benchThis 
- * simply affects the benchmarking object and can be used in inhibit code 
- * movement. The function printResult dumps the measurement information in a 
+ * since this will affect the windows that is measured. The function benchThis
+ * simply affects the benchmarking object and can be used in inhibit code
+ * movement. The function printResult dumps the measurement information in a
  * unibench friendly format.
  *
  * When benchmarking funtions the pragma "noinline" should be specified after
  * the function body to inhibit any inlining optimisations.
+ *
+ * @{
  */
 class C99Benchmarking;
 external classtype;
@@ -428,7 +432,7 @@ void printResults( StringArray::stringArray names, double[.] results)
   printf( "### end descriptions\n");
 }
 
-/*
+/**
  * This function simply affects TheBenchmarkObject and nothing else.
  * Use it to inhibit code movement. The most common use for benchThis
  * is to call it within a function body of a function body that should be
@@ -450,3 +454,4 @@ external void benchDestroyInterval( Interval interval);
 #pragma linksign [1]
 
 #endif /* SAC_BACKEND_C99/CUDA */
+/** @} */

src/auxiliary/Hiding.sac

@@ -1,24 +1,26 @@
-/*****************************************************************************
+/**
+ * @file
+ * @defgroup hiding Hiding
  *
- * file:   Hiding.sac
+ * @brief This module is for hiding type information.
  *
- * description:
+ * It is commonly used for static inputs and is intentioned for benchmarking.
  *
- *   This module is for hiding type information.
- *   It is commonly used for static inputs and is intentioned for benchmarking.
+ * Some functions take a single argument and hide the value, shape or
+ * dimensionality information of the input. Others in addition take an
+ * integer. This allows for calls to inlined kernel functions in a loop
+ * where where the call must be repeated N times for benchmarking.
  *
- *   Some functions take a single argument and hide the value, shape or 
- *   dimensionality information of the input. Others in addition take an
- *   integer. This allows for calls to inlined kernel functions in a loop 
- *   where where the call must be repeated N times for benchmarking.
- *   Here is an example:
- *      for( i=0 ; i < N ; i}}) {
- *        res[[i]] = kernel( hideValue( ip1, i), hideValue( ip2, i), ...);
- *      }
- *   The above code computes kernel N times even if kernel is inlined.
+ * Here is an example:
+ * ~~~~
+ *    for( i=0 ; i < N ; i}}) {
+ *      res[[i]] = kernel( hideValue( ip1, i), hideValue( ip2, i), ...);
+ *    }
+ * ~~~~
+ * The above code computes kernel N times even if kernel is inlined.
  *
- *****************************************************************************/
-
+ * @{
+ */
 module Hiding;
 
 export all;
@@ -42,7 +44,7 @@ inline                                                    \
 TYPE[*] hideValue( int i, TYPE[*] in)                     \
 {                                                         \
   return( _hideValue_SxA_( i, in));                       \
-}                                                         
+}
 HIDEVALUE( int)
 HIDEVALUE( char)
 HIDEVALUE( float)
@@ -96,4 +98,4 @@ HIDEDIMENSIONALITY( char)
 HIDEDIMENSIONALITY( float)
 HIDEDIMENSIONALITY( double)
 HIDEDIMENSIONALITY( bool)
-
+/** @} */

src/auxiliary/Interval.sac

@@ -1,4 +1,12 @@
+/**
+ * @file
+ * @defgroup interval Interval Object
+ * @brief This module provides the Interval classtype
+ *
+ * @{
+ */
 class Interval;
 external classtype;
 
 export {Interval};
+/** @} */

src/classes/auxiliary/Counter.sac

@@ -1,10 +1,10 @@
-/** <!-- ****************************************************************** -->
- * @file Counter.sac
- *
+/**
+ * @file
+ * @defgroup counter Counter
  * @brief A simple class to maintain a global counter
  *
- * @date $Id$
- ******************************************************************************/
+ * @{
+ */
 class Counter;
 
 classtype int;
@@ -13,75 +13,75 @@ use ScalarArith : {+};
 
 export all;
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Creates a new counter with initial value 0.
- * 
+ *
  * @return created counter object
- ******************************************************************************/
+ */
 Counter newCounter()
 {
   return( to_Counter( 0));
 }
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Creates a new counter with initial value v.
- * 
+ *
  * @param v initial value for new counter
- * 
  * @return created counter object
- ******************************************************************************/
+ */
 Counter newCounter( int v)
 {
   return( to_Counter( v));
 }
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Returns the current value of the counter
- * 
+ *
  * @param cnt counter object
- * 
  * @return counter object's value
- ******************************************************************************/
+ */
 int valueOf( Counter &cnt)
 {
   val = from_Counter( cnt);
   cnt = to_Counter( val);
   return( val);
 }
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Increments the counter by one.
- * 
+ *
  * @param cnt the counter object to update
- ******************************************************************************/
+ */
 void increment( Counter &cnt)
 {
   val = from_Counter( cnt);
   cnt = to_Counter( val + 1);
 }
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Increments the counter by the value of the second argument.
  *
  * @param cnt the counter object to update
- ******************************************************************************/
+ * @param x value to increment by
+ */
 void incrementBy( Counter &cnt, int x)
 {
   val = from_Counter( cnt);
   cnt = to_Counter( val + x);
 }
 
-/** <!-- ****************************************************************** -->
+/**
  * @brief Returns the current value of the counter object and
  *        increments the counter object by one
- * 
+ *
  * @param cnt counter object to inspect and modify
- * 
  * @return value of counter object before updating
- ******************************************************************************/
+ */
 int next( Counter &cnt)
 {
   val = valueOf( cnt);
   increment( cnt);
   return( val);
 }
+
+/** @} */

src/classes/random/Rand48.sac

@@ -1,13 +1,14 @@
+/**
+ * @file
+ * @defgroup rand48 Rand48
+ *
+ * Class Rand48 provides a pseudo-random number generator which uses the
+ * linear congruential algorithm and 48-bit integer arithmetic.
+ *
+ * @{
+ */
 class Rand48;
 
-
-    /*
-     *  Class Rand48 provides a pseudo-random number generator which uses the
-     *  linear congruential algorithm and  48-bit  integer 
-     *  arithmetic.
-     */
-
-
 external classtype;
 
 export all;
@@ -20,39 +21,45 @@ external Rand48 randGen();
     #pragma linkobj  "src/Rand48/Rand48.o"
 
 
+/**
+ * @brief Initialize RandomGen to produce a new sequence of pseudo-random
+ *        numbers.
+ * @param SEED value for seed
+ */
 external void srandom(long SEED);
     #pragma effect Rand48::RandomGen
     #pragma linkname "srand48"
     #pragma linkobj  "src/Rand48/Rand48.o"
 
-    /*
-     * Initialize RandomGen to produce a new sequence of pseudo-random
-     * numbers.
-     */
-
-
+/**
+ * @brief Use RandomGen to generate a new pseudo-random integer in the range
+ *        MIN to MAX.
+ *
+ * @param MIN lowest point on range
+ * @param MAX highest point on range
+ * @return pseudo-random value
+ */
 external int random(int MIN, int MAX);
     #pragma linksign [0,1,2]
     #pragma effect Rand48::RandomGen
     #pragma linkname "SACrand48"
     #pragma linkobj  "src/Rand48/Rand48.o"
 
-    /*
-     * Use RandomGen to generate a new pseudo-random integer in the range
-     * MIN to MAX.
-     */
-
-
+/**
+ * brief Use RandomGen to generate a new pseudo-random double precision
+ *       floating-point number in the interval [MIN, MAX).
+ *
+ * @param MIN lowest point on range
+ * @param MAX highest point on range
+ * @return pseudo-random value
+ */
 external double random(double MIN, double MAX);
     #pragma linksign [0,1,2]
     #pragma effect Rand48::RandomGen
     #pragma linkname "SACdrand48"
     #pragma linkobj  "src/Rand48/Rand48.o"
 
-    /*
-     * Use RandomGen to generate a new pseudo-random double precision
-     * floating-point number in the interval [MIN, MAX).
-     */
+
 
 int[*] random( int[.] shp, int MIN, int MAX)
 {
@@ -69,4 +76,4 @@ double[*] random( int[.] shp, double MIN, double MAX)
         } : genarray( shp, 0d );
   return( res);
 }
-
+/** @} */

src/numerical/ComplexMath.sac

@@ -1,3 +1,9 @@
+/**
+ * @file
+ * @defgroup complexmath ComplexMath
+ *
+ * @{
+ */
 module ComplexMath;
 
 export all;
@@ -163,9 +169,4 @@ inline complex sqrt(complex X)
                               ScalarArith::* ((double[2])X)[[1]])))]);
 }
 
-
-
-
-
-
-
+/** @} */