merged AI doc, some new pages

libs/main/math/pistatistic.h

@@ -1,12 +1,11 @@
-/*! \file pistatistic.h
- * \ingroup Math
- * \~\brief
- * \~english Calculating math statistic of values array
- * \~russian Вычисление математической статистики у массива чисел
- */
+//! \~\ingroup Math
+//! \~\file pistatistic.h
+//! \brief
+//! \~english Calculating math statistic of values array
+//! \~russian Вычисление математической статистики у массива чисел
 /*
     PIP - Platform Independent Primitives
-    Class for calculacing math statistic in values array
+	Calculating math statistic of values array
     Andrey Bychkov work.a.b@yandex.ru
 
     This program is free software: you can redistribute it and/or modify
@@ -28,13 +27,24 @@
 
 #include "pimathbase.h"
 
+//! \~\ingroup Math
+//! \~\brief
+//! \~english Template class for calculating statistical measures of a data set
+//! \~russian Шаблонный класс для вычисления статистических характеристик набора данных
+//! \details
+//! \~english Calculates mean, variance, skewness and kurtosis for a numeric sample.
+//! \~russian Вычисляет среднее, дисперсию, асимметрию и эксцесс для числовой выборки.
 template<typename T>
 class PIStatistic {
 	static_assert(std::is_arithmetic<T>::value, "Type must be arithmetic");
 
 public:
+	//! \~english Constructs an object with all accumulated values set to zero.
+	//! \~russian Создает объект со всеми накопленными значениями, равными нулю.
 	PIStatistic() { mean = variance = skewness = kurtosis = T(); }
 
+	//! \~english Returns arithmetic mean of the sample, or zero for an empty vector.
+	//! \~russian Возвращает среднее арифметическое выборки или ноль для пустого вектора.
 	static T calculateMean(const PIVector<T> & val) {
 		T ret = T();
 		int n = val.size();
@@ -43,10 +53,16 @@ public:
 			ret += val[i];
 		return ret / n;
 	}
+
+	//! \~english Calculates all statistics using the supplied mean value.
+	//! \~russian Вычисляет всю статистику, используя переданное среднее значение.
+	//! \~\details
+	//! \~english Returns \c false when the sample contains fewer than two values.
+	//! \~russian Возвращает \c false, если в выборке меньше двух значений.
 	bool calculate(const PIVector<T> & val, const T & given_mean) {
 		T v = T(), v1 = T(), v2 = T(), stddev = T(), var = T();
 		int i, n = val.size();
-		mean     = given_mean;
+		mean = given_mean;
 		if (n < 2) return false;
 		variance = skewness = kurtosis = T();
 		// Variance (using corrected two-pass algorithm)
@@ -72,16 +88,38 @@ public:
 		}
 		return true;
 	}
+
+	//! \~english Calculates all statistics and derives the mean from the sample.
+	//! \~russian Вычисляет всю статистику, определяя среднее по самой выборке.
 	bool calculate(const PIVector<T> & val) { return calculate(val, calculateMean(val)); }
 
+	//! \~english Sample mean.
+	//! \~russian Среднее значение выборки.
 	T mean;
+
+	//! \~english Variance estimate accumulated for the sample.
+	//! \~russian Оценка дисперсии, вычисленная по выборке.
 	T variance;
+
+	//! \~english Sample skewness.
+	//! \~russian Асимметрия выборки.
 	T skewness;
+
+	//! \~english Excess kurtosis of the sample.
+	//! \~russian Эксцесс выборки.
 	T kurtosis;
 };
 
+//! \~english Integer statistics helper.
+//! \~russian Вспомогательный тип статистики для целых чисел.
 typedef PIStatistic<int> PIStatistici;
+
+//! \~english Single-precision statistics helper.
+//! \~russian Вспомогательный тип статистики одинарной точности.
 typedef PIStatistic<float> PIStatisticf;
+
+//! \~english Double-precision statistics helper.
+//! \~russian Вспомогательный тип статистики двойной точности.
 typedef PIStatistic<double> PIStatisticd;
 
 #endif // PISTATISTIC_H