General improvements to documentation and code

src/calculus/integration.h

@@ -151,7 +151,7 @@ namespace theoretica {
 
 			// Richardson extrapolation
 			for (unsigned int k = 1; k <= j; ++k) {
-				const uint64_t coeff = 1 << (2 * k);
+				const uint64_t coeff = uint64_t(1) << (2 * k);
 				T[j][k] = (coeff * T[j][k - 1] - T[j - 1][k - 1]) / (coeff - 1);
 			}
 		}
@@ -187,7 +187,7 @@ namespace theoretica {
 
 			// Richardson extrapolation
 			for (unsigned int k = 1; k <= j; ++k) {
-				const uint64_t coeff = 1 << (2 * k);
+				const uint64_t coeff = uint64_t(1) << (2 * k);
 				T[j][k] = (coeff * T[j][k - 1] - T[j - 1][k - 1]) / (coeff - 1);
 			}
 
@@ -265,7 +265,7 @@ namespace theoretica {
 
 
 	/// Use Gauss-Legendre quadrature of arbitrary degree to approximate
-	/// a definite integral providing the roots of the n degree Legendre polynomial
+	/// a definite integral providing the roots of the n degree Legendre polynomial.
 	///
 	/// @param f The function to integrate
 	/// @param a The lower extreme of integration
@@ -290,7 +290,7 @@ namespace theoretica {
 
 
 	/// Use Gauss-Legendre quadrature of arbitrary degree to approximate
-	/// a definite integral providing the roots of the n degree Legendre polynomial
+	/// a definite integral providing the roots of the n degree Legendre polynomial.
 	///
 	/// @param f The function to integrate
 	/// @param a The lower extreme of integration
@@ -316,7 +316,7 @@ namespace theoretica {
 
 
 	/// Use Gauss-Legendre quadrature of arbitrary degree to approximate
-	/// a definite integral providing the roots of the n degree Legendre polynomial
+	/// a definite integral providing the roots of the n degree Legendre polynomial.
 	///
 	/// @param f The function to integrate
 	/// @param a The lower extreme of integration
@@ -331,8 +331,9 @@ namespace theoretica {
 	}
 
 
-	/// Use Gauss-Legendre quadrature of degree 2, 4, 8, 16 or 32
-	/// using pre-computed values.
+	/// Use Gauss-Legendre quadrature of degree 2, 4, 8 or 16,
+	/// using pre-computed values, to approximate
+	/// an integral over [a, b].
 	///
 	/// @param f The function to integrate
 	/// @param a The lower extreme of integration
@@ -398,12 +399,13 @@ namespace theoretica {
 	}
 
 
-	/// Use Gauss-Laguerre quadrature of degree 2, 4, 8, 16 or 32
-	/// using pre-computed values.
+	/// Use Gauss-Laguerre quadrature of degree 2, 4, 8 or 16,
+	/// using pre-computed values, to approximate
+	/// an integral over [0, +inf).
 	///
 	/// @param f The function to integrate
 	/// @param n The order of the polynomial (available values are
-	/// 2, 4, 8, 16 or 32).
+	/// 2, 4, 8 or 16).
 	/// @return The Gauss-Legendre quadrature of the given function
 	template<typename RealFunction>
 	inline real integral_laguerre(RealFunction f, unsigned int n = 16) {
@@ -440,8 +442,9 @@ namespace theoretica {
 	}
 
 
-	/// Use Gauss-Hermite quadrature of degree 2, 4, 8 or 16
-	/// using pre-computed values.
+	/// Use Gauss-Hermite quadrature of degree 2, 4, 8 or 16,
+	/// using pre-computed values, to approximate
+	/// an integral over (-inf, +inf).
 	///
 	/// @param f The function to integrate
 	/// @param n The order of the polynomial (available values are

src/core/bit_op.h

@@ -14,6 +14,7 @@ namespace theoretica {
 
 	/// Multiply two 64-bit integers and store the result
 	/// in two 64-bit variables, keeping 128 bits of the result.
+	///
 	/// @param a The first number to multiply
 	/// @param b The second number to multiply
 	/// @param c_low The variable where to store the lowest 64 bits
@@ -25,11 +26,11 @@ namespace theoretica {
 		uint64_t& c_low, uint64_t& c_high) {
 
 		// Lowest and highest 32 bits of a and b
-		uint64_t a_low = a & 0xffffffff;
-		uint64_t a_high = a >> 32;
+		const uint64_t a_low = a & 0xffffffff;
+		const uint64_t a_high = a >> 32;
 
-		uint64_t b_low = b & 0xffffffff;
-		uint64_t b_high = b >> 32;
+		const uint64_t b_low = b & 0xffffffff;
+		const uint64_t b_high = b >> 32;
 
 		uint64_t m[4];
 
@@ -50,7 +51,10 @@ namespace theoretica {
 	}
 
 
-	/// MUM bit mixing function
+	/// MUM bit mixing function, computes the 128-bit
+	/// product of a and b and the XOR of their high
+	/// and low 64-bit parts.
+	///
 	/// @param a The first operand
 	/// @param b The second operand
 	inline uint64_t mix_mum(uint64_t a, uint64_t b) {
@@ -62,12 +66,14 @@ namespace theoretica {
 	}
 
 
-	/// Bit rotation using shifting
+	/// Bit rotation of unsigned integer types using shifts.
+	///
 	/// @param x The variable to rotate the bits of
 	/// @param i The index of the rotated bits
-	template<typename ShiftableType>
-	inline ShiftableType bit_rotate(ShiftableType x, unsigned int i) {
-		return (x << i) | (x >> ((sizeof(ShiftableType) * 8) - i));
+	template<typename UnsignedIntType>
+	inline UnsignedIntType bit_rotate(UnsignedIntType x, unsigned int i) {
+
+		return (x << i) | (x >> ((sizeof(UnsignedIntType) * 8) - i));
 	}
 
 }

src/core/function.h

@@ -15,13 +15,18 @@
 
 namespace theoretica {
 
-	/// Function pointer to a real function
+
+	/// Function pointer to a real function of real variable
 	using real_function = std::function<real(real)>;
 
-	/// Function pointer to a complex function
+
+	/// Function pointer to a complex function of complex variable
 	using complex_function = std::function<complex<>(complex<>)>;
 
-	/// Function pointer to a statistical function
+
+	/// Function pointer to a probability distribution function
+	/// where the first argument is the variable and the second
+	/// argument is a vector of the parameters of the distribution.
 	using stat_function = std::function<real(real, const vec<real>&)>;
 
 }

src/core/ratio.h

@@ -19,7 +19,7 @@ namespace theoretica {
 	///
 	/// @note For the class to properly work, the template types
 	/// need to have operator*, operator+ and operator- defined.
-	template <typename T1, typename T2>
+	template <typename T1, typename T2 = T1>
 	class ratio {
 		public:
 
@@ -72,7 +72,7 @@ namespace theoretica {
 			}
 
 			/// Evaluate the ratio as the division
-			/// between numerator and denominator converted
+			/// between numerator and denominator cast
 			/// to the specified type.
 			///
 			/// This function is well-defined only if division
@@ -85,15 +85,15 @@ namespace theoretica {
 
 
 			/// Evaluate the ratio as the division
-			/// between numerator and denominator converted
+			/// between numerator and denominator cast
 			/// to the type of the denominator.
 			inline T2 eval() {
 				return static_cast<T2>(num) / static_cast<T2>(den);
 			}
 
 
 			/// Evaluate the ratio as the division
-			/// between numerator and denominator converted
+			/// between numerator and denominator cast
 			/// to the type of the denominator.
 			///
 			/// @see eval

src/pseudorandom/rand_dist.h

@@ -1,5 +1,5 @@
 
-/// @file rand_dist.h Random numbers following a pdf
+/// @file rand_dist.h Sampling from a probability distribution
 
 #ifndef THEORETICA_RAND_DIST_H
 #define THEORETICA_RAND_DIST_H