# HG changeset patch
# User Chris Cannam <c.cannam@qmul.ac.uk>
# Date 1382352609 -3600
# Node ID 59b151f13b3e906ff192d2df5dad56400b1f1f51
# Parent  8e32cd2af755d21e63ff07561776e9770dcea665
Some docs

diff -r 8e32cd2af755 -r 59b151f13b3e base/KaiserWindow.h
--- a/base/KaiserWindow.h	Mon Oct 21 11:38:40 2013 +0100
+++ b/base/KaiserWindow.h	Mon Oct 21 11:50:09 2013 +0100
@@ -17,6 +17,11 @@
 #include <vector>
 #include <cmath>
 
+/**
+ * Kaiser window: A windower whose bandwidth and sidelobe height
+ * (signal-noise ratio) can be specified. These parameters are traded
+ * off against the window length.
+ */
 class KaiserWindow
 {
 public:
diff -r 8e32cd2af755 -r 59b151f13b3e base/Pitch.h
--- a/base/Pitch.h	Mon Oct 21 11:38:40 2013 +0100
+++ b/base/Pitch.h	Mon Oct 21 11:50:09 2013 +0100
@@ -15,6 +15,10 @@
 #ifndef _PITCH_H_
 #define _PITCH_H_
 
+/**
+ * Convert between musical pitch (i.e. MIDI pitch number) and
+ * fundamental frequency.
+ */
 class Pitch
 {
 public:
diff -r 8e32cd2af755 -r 59b151f13b3e base/SincWindow.h
--- a/base/SincWindow.h	Mon Oct 21 11:38:40 2013 +0100
+++ b/base/SincWindow.h	Mon Oct 21 11:50:09 2013 +0100
@@ -16,6 +16,10 @@
 
 #include <vector>
 
+/**
+ * A window containing values of the sinc function, i.e. sin(x)/x with
+ * sinc(0) == 1, with x == 0 at the centre.
+ */
 class SincWindow
 {
 public:
diff -r 8e32cd2af755 -r 59b151f13b3e base/Window.h
--- a/base/Window.h	Mon Oct 21 11:38:40 2013 +0100
+++ b/base/Window.h	Mon Oct 21 11:50:09 2013 +0100
@@ -30,6 +30,10 @@
     LastWindow = BlackmanWindow
 };
 
+/**
+ * Various shaped windows for sample frame conditioning, including
+ * cosine windows (Hann etc) and triangular and rectangular windows.
+ */
 template <typename T>
 class Window
 {
diff -r 8e32cd2af755 -r 59b151f13b3e maths/MathUtilities.h
--- a/maths/MathUtilities.h	Mon Oct 21 11:38:40 2013 +0100
+++ b/maths/MathUtilities.h	Mon Oct 21 11:50:09 2013 +0100
@@ -20,20 +20,57 @@
 
 #include "nan-inf.h"
 
+/**
+ * Static helper functions for simple mathematical calculations.
+ */
 class MathUtilities  
 {
 public:	
+    /**
+     * Round x to the nearest integer.
+     */
     static double round( double x );
 
+    /**
+     * Return through min and max pointers the highest and lowest
+     * values in the given array of the given length.
+     */
     static void	  getFrameMinMax( const double* data, unsigned int len,  double* min, double* max );
 
+    /**
+     * Return the mean of the given array of the given length.
+     */
     static double mean( const double* src, unsigned int len );
+
+    /**
+     * Return the mean of the subset of the given vector identified by
+     * start and count.
+     */
     static double mean( const std::vector<double> &data,
                         unsigned int start, unsigned int count );
+    
+    /**
+     * Return the sum of the values in the given array of the given
+     * length.
+     */
     static double sum( const double* src, unsigned int len );
+
+    /**
+     * Return the median of the values in the given array of the given
+     * length. If the array is even in length, the returned value will
+     * be half-way between the two values adjacent to median.
+     */
     static double median( const double* src, unsigned int len );
 
+    /**
+     * The principle argument function. Map the phase angle ang into
+     * the range [-pi,pi).
+     */
     static double princarg( double ang );
+
+    /**
+     * Floating-point division modulus: return x % y.
+     */
     static double mod( double x, double y);
 
     static void	  getAlphaNorm(const double *data, unsigned int len, unsigned int alpha, double* ANorm);
@@ -57,16 +94,43 @@
     static void normalise(std::vector<double> &data,
                           NormaliseType n = NormaliseUnitMax);
 
-    // moving mean threshholding:
+    /**
+     * Threshold the input/output vector data against a moving-mean
+     * average filter.
+     */
     static void adaptiveThreshold(std::vector<double> &data);
 
+    /** 
+     * Return true if x is 2^n for some integer n >= 0.
+     */
     static bool isPowerOfTwo(int x);
-    static int nextPowerOfTwo(int x); // e.g. 1300 -> 2048, 2048 -> 2048
-    static int previousPowerOfTwo(int x); // e.g. 1300 -> 1024, 2048 -> 2048
-    static int nearestPowerOfTwo(int x); // e.g. 1300 -> 1024, 12 -> 16 (not 8)
 
+    /**
+     * Return the next higher integer power of two from x, e.g. 1300
+     * -> 2048, 2048 -> 2048.
+     */
+    static int nextPowerOfTwo(int x);
+
+    /**
+     * Return the next lower integer power of two from x, e.g. 1300 ->
+     * 1024, 2048 -> 2048.
+     */
+    static int previousPowerOfTwo(int x);
+
+    /**
+     * Return the nearest integer power of two to x, e.g. 1300 -> 1024,
+     * 12 -> 16 (not 8; if two are equidistant, the higher is returned).
+     */
+    static int nearestPowerOfTwo(int x);
+
+    /**
+     * Return x!
+     */
     static double factorial(int x); // returns double in case it is large
 
+    /**
+     * Return the greatest common divisor of natural numbers a and b.
+     */
     static int gcd(int a, int b);
 };